Basic Java documentation of Skylark Annotations

@SkylarkCallable and @SkylarkSignature were undocumented, making
it hard for the developer to understand these annotations.

This change add basic documentation for them.

--
MOS_MIGRATED_REVID=124461858

2 files changed, 132 insertions, 1 deletions

diff --git a/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkCallable.java b/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkCallable.java
index a2a720b309..86d2c88e3d 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkCallable.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkCallable.java
@@ -24,13 +24,35 @@ import java.lang.annotation.Target;
 @Target({ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface SkylarkCallable {
+
+  /**
+   * Name of the method, as exposed to Skylark.
+   */
   String name() default "";
 
-  String doc() default ""; // only allowed to be empty if documented() is false.
+  /**
+   * The documentation text in Skylark. It can contain HTML tags for special formatting.
+   *
+   * <p>It is allowed to be empty only if {@link #documented()} is false.
+   */
+  String doc() default "";
 
+  /**
+   * If true, the function will appear in the Skylark documentation. Set this to false if the
+   * function is experimental or an overloading and doesn't need to be documented.
+   */
   boolean documented() default true;
 
+  /**
+   * If true, this method will be considered as a field of the enclosing Java object. E.g., if set
+   * to true on a method {@code foo}, then the callsites of this method will look like
+   * {@code bar.foo} instead of {@code bar.foo()}. The annotated method must be parameterless.
+   */
   boolean structField() default false;
 
+  /**
+   * Set it to true if the Java method may return <code>null</code> (which will then be converted to
+   * <code>None</code>). If not set and the Java method returns null, an error will be raised.
+   */
   boolean allowReturnNones() default false;
 }
diff --git a/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkSignature.java b/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkSignature.java
index eed1888e7e..afe8e9624e 100644
--- a/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkSignature.java
+++ b/src/main/java/com/google/devtools/build/lib/skylarkinterface/SkylarkSignature.java
@@ -21,6 +21,25 @@ import java.lang.annotation.Target;
 
 /**
  * An annotation to mark built-in keyword argument methods accessible from Skylark.
+ *
+ * <p>Use this annotation around a {@link com.google.devtools.build.lib.syntax.BuiltinFunction} or
+ * a {@link com.google.devtools.build.lib.syntax.BuiltinFunction.Factory}. The annotated function
+ * should expect the arguments described by {@link #parameters()},
+ * {@link #optionalPositionals()}, {@link #extraPositionals()}, {@link #mandatoryNamedOnly()},
+ * {@link #optionalNamedOnly()} and {@link #extraKeywords()}. It should also expect the following
+ * extraneous arguments:
+ *
+ * <ul>
+ *   <li>
+ *     {@link com.google.devtools.build.lib.events.Location} if {@link #useLocation()} is
+ *     true.
+ *   </li>
+ *   <li>{@link com.google.devtools.build.lib.syntax.ASTNode} if {@link #useAst()} is true.</li>
+ *   <li>
+ *     {@link com.google.devtools.build.lib.syntax.Environment} if {@link #useEnvironment()} )}
+ *     is true.
+ *   </li>
+ * </ul>
  */
 @Target({ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)
@@ -30,35 +49,94 @@ public @interface SkylarkSignature {
   // in Skylark syntax, e.g.: signature = "foo(a: string, b: ListOf(int)) -> NoneType"
   // String signature() default "";
 
+  /**
+   * Name of the method as exposed to Skylark.
+   */
   String name();
 
+  /**
+   * General documentation block of the method. See the skylark documentation at
+   * http://www.bazel.io/docs/skylark/.
+   */
   String doc() default "";
 
+  /**
+   * List of mandatory positional parameters for calling this method. These parameters have
+   * to be placed first in the list of arguments when calling that method.
+   */
   Param[] mandatoryPositionals() default {};
 
+  /**
+   * List of optional positional parameters for calling this method. These parameters have
+   * to be placed before any named parameters when calling the method.
+   */
   Param[] optionalPositionals() default {};
 
+  /**
+   * List of optional named parameters for calling this method. These parameters can be specified
+   * in the list of arguments using the <code>key=value</code> format in calling the method.
+   */
   Param[] optionalNamedOnly() default {};
 
+  /**
+   * List of mandatory named parameters for calling this method. These parameters must be specified
+   * in the list of arguments using the <code>key=value</code> format in calling the method.
+   */
   Param[] mandatoryNamedOnly() default {};
 
+  /**
+   * Defines a catch all positional parameters. By default, it is an error to define more
+   * positional parameters that specified but by defining an extraPositionals argument, one can
+   * catch those. See python's <code>*args</code>
+   * (http://thepythonguru.com/python-args-and-kwargs/).
+   */
   Param extraPositionals() default @Param(name = "");
 
+  /**
+   * Defines a catch all named parameters. By default, it is an error to define more
+   * named parameters that specified but by defining an extraKeywords argument, one can catch those.
+   * See python's <code>**kwargs</code> (http://thepythonguru.com/python-args-and-kwargs/).
+   */
   Param extraKeywords() default @Param(name = "");
 
+  /**
+   * Set <code>documented</code> to <code>false</code> if this method should not be mentioned
+   * in the documentation of Skylark. This is generally used for experimental APIs or duplicate
+   * methods already documented on another call.
+   */
   boolean documented() default true;
 
+  /**
+   * Type of the object associated to that function. If this field is
+   * <code>Object.class</code>, then the function will be considered as an object method.
+   * For example, to add a function to the string object, set it to <code>String.class</code>.
+   */
   Class<?> objectType() default Object.class;
 
+  /**
+   * Return type of the function. Use {@link com.google.devtools.build.lib.syntax.Runtime.NoneType}
+   * for a void function.
+   */
   Class<?> returnType() default Object.class;
 
   // TODO(bazel-team): determine this way whether to accept mutable Lists
   // boolean mutableLists() default false;
 
+  /**
+   * If true the location of the call site will be passed as an argument of the annotated function.
+   */
   boolean useLocation() default false;
 
+  /**
+   * If true the AST of the call site will be passed as an argument of the annotated function.
+   */
   boolean useAst() default false;
 
+  /**
+   * If true the AST of the Skylark Environment
+   * ({@link com.google.devtools.build.lib.syntax.Environment}) will be passed as an argument of the
+   * annotated function.
+   */
   boolean useEnvironment() default false;
 
   /**
@@ -67,18 +145,49 @@ public @interface SkylarkSignature {
   @Retention(RetentionPolicy.RUNTIME)
   public @interface Param {
 
+    /**
+     * Name of the parameter, as viewed from Skylark. Used for named parameters and for generating
+     * documentation.
+     */
     String name();
 
+    /**
+     * Documentation of the parameter.
+     */
     String doc() default "";
 
+    /**
+     * Default value for the parameter, as a Skylark value (e.g. "False", "True", "[]", "None").
+     */
     String defaultValue() default "";
 
+    /**
+     * Type of the parameter, e.g. {@link String}.class or
+     * {@link com.google.devtools.build.lib.syntax.SkylarkList}.class.
+     */
     Class<?> type() default Object.class;
 
+    /**
+     * When {@link #type()} is a generic type (e.g.,
+     * {@link com.google.devtools.build.lib.syntax.SkylarkList}), specify the type parameter (e.g.
+     * {@link String}.class} along with {@link com.google.devtools.build.lib.syntax.SkylarkList} for
+     * {@link #type()} to specify a list of strings).
+     */
     Class<?> generic1() default Object.class;
 
+    /**
+     * Whether the name of a callback function can be given instead of a computed value. If a
+     * callback function is used then the value of this parameter will be computed only when
+     * actually requested. E.g., if a parameter {@code foo} of a function {@code bar} is passed a
+     * callback function, then only when the method {@code bar} actually asks for the value
+     * {@code foo}, replacing it by a
+     * {@link com.google.devtools.build.lib.syntax.SkylarkCallbackFunction} in between.
+     */
     boolean callbackEnabled() default false;
 
+    /**
+     * If true, this parameter can be passed the "None" value.
+     */
     boolean noneable() default false;
 
     // TODO(bazel-team): parse the type from a single field in Skylark syntax,