Skylark documentation: Replace "set" and "List" plain-text return types with links to "deptset" and "list".
PiperOrigin-RevId: 162607082
diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkDoc.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkDoc.java
index b3e2960..0397ee7 100644
--- a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkDoc.java
@@ -13,6 +13,8 @@
// limitations under the License.
package com.google.devtools.build.docgen.skylark;
+import com.google.common.collect.ImmutableList;
+import com.google.devtools.build.lib.collect.nestedset.NestedSet;
import com.google.devtools.build.lib.skylarkinterface.Param;
import com.google.devtools.build.lib.skylarkinterface.SkylarkModule;
import com.google.devtools.build.lib.skylarkinterface.SkylarkSignature;
@@ -56,12 +58,14 @@
return "<a class=\"anchor\" href=\"dict.html\">dict</a>";
} else if (type.equals(Tuple.class)) {
return "<a class=\"anchor\" href=\"list.html\">tuple</a>";
- } else if (type.equals(MutableList.class)) {
+ } else if (type.equals(MutableList.class) || type.equals(ImmutableList.class)) {
return "<a class=\"anchor\" href=\"list.html\">list</a>";
} else if (type.equals(SkylarkList.class)) {
return "<a class=\"anchor\" href=\"list.html\">sequence</a>";
} else if (type.equals(Void.TYPE) || type.equals(NoneType.class)) {
return "<a class=\"anchor\" href=\"" + TOP_LEVEL_ID + ".html#None\">None</a>";
+ } else if (type.equals(NestedSet.class)) {
+ return "<a class=\"anchor\" href=\"depset.html\">depset</a>";
} else if (type.isAnnotationPresent(SkylarkModule.class)) {
SkylarkModule module = type.getAnnotation(SkylarkModule.class);
if (module.documented()) {
diff --git a/src/main/java/com/google/devtools/build/lib/syntax/EvalUtils.java b/src/main/java/com/google/devtools/build/lib/syntax/EvalUtils.java
index e6e9089..0fa8570 100644
--- a/src/main/java/com/google/devtools/build/lib/syntax/EvalUtils.java
+++ b/src/main/java/com/google/devtools/build/lib/syntax/EvalUtils.java
@@ -251,7 +251,7 @@
return "select";
} else if (NestedSet.class.isAssignableFrom(c)) {
// TODO(bazel-team): no one should be seeing naked NestedSet at all.
- return "set";
+ return "depset";
} else {
if (c.getSimpleName().isEmpty()) {
return c.getName();
diff --git a/src/test/java/com/google/devtools/build/docgen/BUILD b/src/test/java/com/google/devtools/build/docgen/BUILD
index 6c21717..475e74c 100644
--- a/src/test/java/com/google/devtools/build/docgen/BUILD
+++ b/src/test/java/com/google/devtools/build/docgen/BUILD
@@ -42,6 +42,7 @@
":testutil",
"//src/main/java/com/google/devtools/build/docgen:docgen_javalib",
"//src/main/java/com/google/devtools/build/lib:build-base",
+ "//src/main/java/com/google/devtools/build/lib:collect",
"//src/main/java/com/google/devtools/build/lib:packages-internal",
"//src/main/java/com/google/devtools/build/lib:skylarkinterface",
"//src/main/java/com/google/devtools/build/lib:syntax",
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 b491d26..29779de 100644
--- a/src/test/java/com/google/devtools/build/docgen/SkylarkDocumentationTest.java
+++ b/src/test/java/com/google/devtools/build/docgen/SkylarkDocumentationTest.java
@@ -17,17 +17,22 @@
import static com.google.common.truth.Truth.assertWithMessage;
import com.google.common.base.Function;
+import com.google.common.collect.ImmutableList;
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.collect.nestedset.NestedSet;
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.SkylarkList;
+import com.google.devtools.build.lib.syntax.SkylarkList.MutableList;
+import com.google.devtools.build.lib.syntax.SkylarkList.Tuple;
import com.google.devtools.build.lib.syntax.util.EvaluationTestCase;
import java.lang.reflect.Method;
import java.util.ArrayList;
@@ -37,6 +42,7 @@
import java.util.Map;
import java.util.Map.Entry;
import java.util.TreeMap;
+import java.util.stream.Collectors;
import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;
@@ -161,6 +167,37 @@
}
}
+ /** MockClassWithContainerReturnValues */
+ @SkylarkModule(name = "MockClassWithContainerReturnValues",
+ doc = "MockClassWithContainerReturnValues")
+ private static class MockClassWithContainerReturnValues {
+
+ @SkylarkCallable(name = "depset", doc = "depset")
+ public NestedSet<Integer> getNestedSet() {
+ return null;
+ }
+
+ @SkylarkCallable(name = "tuple", doc = "tuple")
+ public Tuple<Integer> getTuple() {
+ return null;
+ }
+
+ @SkylarkCallable(name = "immutable", doc = "immutable")
+ public ImmutableList<Integer> getImmutableList() {
+ return null;
+ }
+
+ @SkylarkCallable(name = "mutable", doc = "mutable")
+ public MutableList<Integer> getMutableList() {
+ return null;
+ }
+
+ @SkylarkCallable(name = "skylark", doc = "skylark")
+ public SkylarkList<Integer> getSkylarkList() {
+ return null;
+ }
+ }
+
@Test
public void testSkylarkJavaInterfaceExplorerOnSimpleClass() throws Exception {
Map<String, SkylarkModuleDoc> objects = collect(MockClassA.class);
@@ -216,6 +253,38 @@
.isEqualTo("<a class=\"anchor\" href=\"int.html\">int</a> MockClassE.get()");
}
+ @Test
+ public void testSkylarkContainerReturnTypesWithoutAnnotations() throws Exception {
+ Map<String, SkylarkModuleDoc> objects = collect(MockClassWithContainerReturnValues.class);
+ assertThat(objects).containsKey("MockClassWithContainerReturnValues");
+ Collection<SkylarkMethodDoc> methods =
+ objects.get("MockClassWithContainerReturnValues").getMethods();
+
+ List<String> signatures =
+ methods.stream().map(m -> m.getSignature()).collect(Collectors.toList());
+ assertThat(signatures).hasSize(5);
+ assertThat(signatures)
+ .contains(
+ "<a class=\"anchor\" href=\"depset.html\">depset</a> "
+ + "MockClassWithContainerReturnValues.depset()");
+ assertThat(signatures)
+ .contains(
+ "<a class=\"anchor\" href=\"list.html\">tuple</a> "
+ + "MockClassWithContainerReturnValues.tuple()");
+ assertThat(signatures)
+ .contains(
+ "<a class=\"anchor\" href=\"list.html\">list</a> "
+ + "MockClassWithContainerReturnValues.immutable()");
+ assertThat(signatures)
+ .contains(
+ "<a class=\"anchor\" href=\"list.html\">list</a> "
+ + "MockClassWithContainerReturnValues.mutable()");
+ assertThat(signatures)
+ .contains(
+ "<a class=\"anchor\" href=\"list.html\">sequence</a> "
+ + "MockClassWithContainerReturnValues.skylark()");
+ }
+
private Iterable<Method> extractMethods(Collection<SkylarkJavaMethodDoc> methods) {
return Iterables.transform(methods, new Function<SkylarkJavaMethodDoc, Method>() {
@Override
