Skylark documentation: Replace "set" and "List" plain-text return types with links to "deptset" and "list".

PiperOrigin-RevId: 162607082

4 files changed, 76 insertions, 2 deletions

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 b3e2960c26..0397ee7cc9 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 @@ abstract class SkylarkDoc {
       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 e6e9089f43..0fa85706f1 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 @@ public final class EvalUtils {
       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 6c21717373..475e74c70a 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 @@ java_library(
         ":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 b491d26049..29779dede7 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.assertThat;
 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.List;
 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 @@ public class SkylarkDocumentationTest extends SkylarkTestCase {
     }
   }
 
+  /** 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 @@ public class SkylarkDocumentationTest extends SkylarkTestCase {
         .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