Add JsEnum and JsAsync annotations. Also started allowing one line JavaDoc comments since they are widely used now. Change-Id: I602b542f2c31b21ada0aba8c92e2d80c7563fd56
diff --git a/eclipse/settings/code-style/gwt-checkstyle-tests.xml b/eclipse/settings/code-style/gwt-checkstyle-tests.xml index b487425..fc45c2e 100644 --- a/eclipse/settings/code-style/gwt-checkstyle-tests.xml +++ b/eclipse/settings/code-style/gwt-checkstyle-tests.xml
@@ -184,14 +184,6 @@ <property name="severity" value="error"/> <property name="format" value="@author"/> </module> - <module name="Regexp"> - <metadata name="com.atlassw.tools.eclipse.checkstyle.comment" value="No one line javadoc comments"/> - <metadata name="com.atlassw.tools.eclipse.checkstyle.lastEnabledSeverity" value="error"/> - <property name="severity" value="ignore"/> - <property name="format" value="[/][*][*][^\n]*[*][/]"/> - <property name="message" value="No one line javadoc comments"/> - <property name="illegalPattern" value="true"/> - </module> <module name="MemberName"> <property name="severity" value="ignore"/> <property name="format" value="^[a-z_][a-zA-Z0-9_]*$"/>
diff --git a/eclipse/settings/code-style/gwt-checkstyle.xml b/eclipse/settings/code-style/gwt-checkstyle.xml index 41fdcea..81da7af 100644 --- a/eclipse/settings/code-style/gwt-checkstyle.xml +++ b/eclipse/settings/code-style/gwt-checkstyle.xml
@@ -171,13 +171,6 @@ <property name="severity" value="error"/> <property name="format" value="@author"/> </module> - <module name="Regexp"> - <metadata name="com.atlassw.tools.eclipse.checkstyle.comment" value="No one line javadoc comments"/> - <property name="severity" value="error"/> - <property name="format" value="[/][*][*][^\n]*[*][/]"/> - <property name="message" value="No one line javadoc comments"/> - <property name="illegalPattern" value="true"/> - </module> <module name="NoWhitespaceAfter"> <property name="severity" value="error"/> <property name="allowLineBreaks" value="false"/>
diff --git a/user/src/jsinterop/annotations/JsAsync.java b/user/src/jsinterop/annotations/JsAsync.java new file mode 100644 index 0000000..894856c --- /dev/null +++ b/user/src/jsinterop/annotations/JsAsync.java
@@ -0,0 +1,42 @@ +/* + * Copyright 2017 Google Inc. + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not + * use this file except in compliance with the License. You may obtain a copy of + * the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + * License for the specific language governing permissions and limitations under + * the License. + */ +package jsinterop.annotations; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * JsAsync marks a method to be transpiled to an async JavaScript method. + * + * <p>Adding this annotation to a method adds an {@code async} keyword to the generated JavaScript + * function. + * + * <p>There are some limitations apply on JsAsync to make the annotation practical: + * <ul> + * <li>A @JsAsync method return type should be IThenable or Promise. + * <li>A @JsAsync method should not return {@code null}. + * </ul> + * + * <p>This is an EXPERIMENTAL annotation and only works in J2CL. + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) +@Documented +public @interface JsAsync { +}
diff --git a/user/src/jsinterop/annotations/JsEnum.java b/user/src/jsinterop/annotations/JsEnum.java new file mode 100644 index 0000000..3332821 --- /dev/null +++ b/user/src/jsinterop/annotations/JsEnum.java
@@ -0,0 +1,91 @@ +/* + * Copyright 2018 Google Inc. + * + * Licensed under the Apache License, Version 2.0 (the "License"); you may not + * use this file except in compliance with the License. You may obtain a copy of + * the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT + * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the + * License for the specific language governing permissions and limitations under + * the License. + */ +package jsinterop.annotations; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * JsEnum marks a Java enum as being represented as a Closure enum, either one that already exists + * from the external JavaScript environment, or one that will be accessible from the external + * JavaScript environment. + * + * <p>The underlying type of the Closure enum can be specified via {@link #hasCustomValue} and + * declaring an instance field named "value" of the desired type. + * + * <p>If the JsEnum is non-native and has custom values, a constructor is required to allow + * specifying the values for the enum constants, as in the following example + * + * <pre><code> + * {@literal @}JsEnum(hasCustomValue=true) + * enum IntJsEnum { + * TEN(10), + * TWENTY(20); + * + * int value; + * + * IntJsEnum(int value) { this.value = value; } + * } + * </code></pre> + * + * <p>If the JsEnum is native and has custom values, the value field is still required but + * constructors are not needed nor allowed. + * + * <p>JsEnums do not support the full Java semantics: + * + * <ul> + * <li>No instance fields are allowed other than {@code value}, + * <li>{@link Enum#name()} and {@link Enum#values()} are not supported. + * <li>{@link Enum#ordinal()} is supported only for non-native JsEnums that don't have custom + * values. + * <li>The class is initialization might be delayed until a static field/method is accessed. + * </ul> + * + * <p>The JavaScript namespace and name can be specified in a manner similar to JsTypes via {@link + * #namespace} and {@link #name} respectively. + * + * <p>Methods and fields declared in the JsEnum are only accessible in Java code. Only the enum + * constants are accessible from JavaScript code. + * + * <p>This annotation is only supported by J2CL. + */ +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.TYPE) +@Documented +public @interface JsEnum { + + /** + * Customizes the name of the type in generated JavaScript. If not provided, the simple Java name + * will be used. + */ + String name() default "<auto>"; + + /** Customizes the namespace of the type in generated JavaScript. */ + String namespace() default "<auto>"; + + /** When set to {@code true}, this JsEnum is a native Closure enum type. */ + boolean isNative() default false; + + /** + * When set to {@code true}, this JsEnum will have a custom value defined by a field named + * 'value'. The only allowed types for the value field are String and primitive types with the + * exception of long. + */ + boolean hasCustomValue() default false; +}