Generate documentation for named parameters for SkylarkCallable

Fixes #1470.

--
Change-Id: If16e32ac6e9b71680b6ed73987f1164545a99920
Reviewed-on: https://bazel-review.googlesource.com/#/c/5670/
MOS_MIGRATED_REVID=132243744

2 files changed, 36 insertions, 14 deletions

diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkJavaMethodDoc.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkJavaMethodDoc.java
index 66b5f97989..f31123741e 100644
--- a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkJavaMethodDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkJavaMethodDoc.java
@@ -13,9 +13,12 @@
 // limitations under the License.
 package com.google.devtools.build.docgen.skylark;
 
+import com.google.common.collect.ImmutableList;
+import com.google.devtools.build.lib.skylarkinterface.Param;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable;
 import com.google.devtools.build.lib.util.StringUtilities;
 import java.lang.reflect.Method;
+import java.util.List;
 
 /**
  * A class representing a Java method callable from Skylark with annotation.
@@ -25,6 +28,7 @@ public final class SkylarkJavaMethodDoc extends SkylarkMethodDoc {
   private final String name;
   private final Method method;
   private final SkylarkCallable callable;
+  private final ImmutableList<SkylarkParamDoc> params;
 
   public SkylarkJavaMethodDoc(SkylarkModuleDoc module, Method method,
       SkylarkCallable callable) {
@@ -34,6 +38,11 @@ public final class SkylarkJavaMethodDoc extends SkylarkMethodDoc {
         : callable.name();
     this.method = method;
     this.callable = callable;
+    ImmutableList.Builder<SkylarkParamDoc> paramsBuilder = ImmutableList.builder();
+    for (Param param : callable.parameters()) {
+      paramsBuilder.add(new SkylarkParamDoc(this, param));
+    }
+    this.params = paramsBuilder.build();
   }
 
   public Method getMethod() {
@@ -67,4 +76,9 @@ public final class SkylarkJavaMethodDoc extends SkylarkMethodDoc {
     }
     return "";
   }
+
+  @Override
+  public List<SkylarkParamDoc> getParams() {
+    return params;
+  }
 }
diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkMethodDoc.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkMethodDoc.java
index 870a10d43a..c0ab2667f3 100644
--- a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkMethodDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkMethodDoc.java
@@ -13,14 +13,11 @@
 // limitations under the License.
 package com.google.devtools.build.docgen.skylark;
 
-import com.google.common.base.Function;
 import com.google.common.base.Joiner;
 import com.google.common.collect.ImmutableList;
-import com.google.common.collect.Iterables;
 import com.google.devtools.build.lib.skylarkinterface.Param;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkSignature;
-
 import java.lang.reflect.Method;
 import java.util.ArrayList;
 import java.util.List;
@@ -28,10 +25,8 @@ import java.util.List;
 /**
  * An abstract class containing documentation for a Skylark method.
  */
-abstract class SkylarkMethodDoc extends SkylarkDoc {
-  /**
-   * Returns whether the Skylark method is documented.
-   */
+public abstract class SkylarkMethodDoc extends SkylarkDoc {
+  /** Returns whether the Skylark method is documented. */
   public abstract boolean documented();
 
   /**
@@ -57,13 +52,26 @@ abstract class SkylarkMethodDoc extends SkylarkDoc {
   }
 
   private String getParameterString(Method method) {
-    return Joiner.on(", ").join(Iterables.transform(
-        ImmutableList.copyOf(method.getParameterTypes()), new Function<Class<?>, String>() {
-          @Override
-          public String apply(Class<?> input) {
-            return getTypeAnchor(input);
-          }
-        }));
+    SkylarkCallable annotation = method.getAnnotation(SkylarkCallable.class);
+    int nbPositional = annotation.mandatoryPositionals();
+    if (annotation.parameters().length > 0 && nbPositional < 0) {
+      nbPositional = 0;
+    }
+    List<String> argList = new ArrayList<>();
+    for (int i = 0; i < nbPositional; i++) {
+      argList.add("arg" + i + ":" + getTypeAnchor(method.getParameterTypes()[i]));
+    }
+    boolean named = false;
+    for (Param param : annotation.parameters()) {
+      if (param.named() && !param.positional() && !named) {
+        named = true;
+        if (!argList.isEmpty()) {
+          argList.add("*");
+        }
+      }
+      argList.add(formatParameter(param));
+    }
+    return Joiner.on(", ").join(argList);
   }
 
   protected String getSignature(String objectName, String methodName, Method method) {