diff options
3 files changed, 72 insertions, 20 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) { diff --git a/src/test/java/com/google/devtools/build/docgen/SkylarkDocumentationTest.java b/src/test/java/com/google/devtools/build/docgen/SkylarkDocumentationTest.java index 04a3376865..cb8a039a88 100644 --- a/src/test/java/com/google/devtools/build/docgen/SkylarkDocumentationTest.java +++ b/src/test/java/com/google/devtools/build/docgen/SkylarkDocumentationTest.java @@ -20,19 +20,15 @@ import com.google.common.base.Function; import com.google.common.collect.Iterables; import com.google.devtools.build.docgen.skylark.SkylarkBuiltinMethodDoc; import com.google.devtools.build.docgen.skylark.SkylarkJavaMethodDoc; +import com.google.devtools.build.docgen.skylark.SkylarkMethodDoc; import com.google.devtools.build.docgen.skylark.SkylarkModuleDoc; import com.google.devtools.build.lib.rules.SkylarkRuleContext; import com.google.devtools.build.lib.skylark.util.SkylarkTestCase; +import com.google.devtools.build.lib.skylarkinterface.Param; import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable; import com.google.devtools.build.lib.skylarkinterface.SkylarkModule; import com.google.devtools.build.lib.syntax.Environment; import com.google.devtools.build.lib.syntax.util.EvaluationTestCase; - -import org.junit.Before; -import org.junit.Test; -import org.junit.runner.RunWith; -import org.junit.runners.JUnit4; - import java.lang.reflect.Method; import java.util.ArrayList; import java.util.Collection; @@ -41,6 +37,10 @@ import java.util.List; import java.util.Map; import java.util.Map.Entry; import java.util.TreeMap; +import org.junit.Before; +import org.junit.Test; +import org.junit.runner.RunWith; +import org.junit.runners.JUnit4; /** * Tests for Skylark documentation. @@ -132,6 +132,22 @@ public class SkylarkDocumentationTest extends SkylarkTestCase { } } + @SkylarkModule(name = "MockClassD", doc = "MockClassD") + public static class MockClassD { + @SkylarkCallable( + doc = "MockClassD#test", + mandatoryPositionals = 1, + parameters = { + @Param(name = "b"), + @Param(name = "c", named = true, positional = false), + @Param(name = "d", named = true, positional = false, defaultValue = "1"), + } + ) + public Integer test(int a, int b, int c, int d) { + return 0; + } + } + @Test public void testSkylarkJavaInterfaceExplorerOnSimpleClass() throws Exception { Map<String, SkylarkModuleDoc> objects = collect(MockClassA.class); @@ -155,6 +171,20 @@ public class SkylarkDocumentationTest extends SkylarkTestCase { MockClassA.class.getMethod("get"), MockClassC.class.getMethod("get2")); } + @Test + public void testSkylarkCallableParameters() throws Exception { + Map<String, SkylarkModuleDoc> objects = collect(MockClassD.class); + assertThat(objects).hasSize(1); + assertThat(objects).containsKey("MockClassD"); + SkylarkModuleDoc moduleDoc = objects.get("MockClassD"); + assertThat(moduleDoc.getDocumentation()).isEqualTo("MockClassD."); + assertThat(moduleDoc.getMethods()).hasSize(1); + SkylarkMethodDoc methodDoc = moduleDoc.getMethods().iterator().next(); + assertThat(methodDoc.getDocumentation()).isEqualTo("MockClassD#test."); + assertThat(methodDoc.getSignature()).isEqualTo("int MockClassD.test(arg0:int, b, *, c, d=1)"); + assertThat(methodDoc.getParams()).hasSize(3); + } + private Iterable<Method> extractMethods(Collection<SkylarkJavaMethodDoc> methods) { return Iterables.transform(methods, new Function<SkylarkJavaMethodDoc, Method>() { @Override |