Generate documentation for bool and int types.

This improves consistency in the documentation (string and list already have their own page). -- PiperOrigin-RevId: 147599068 MOS_MIGRATED_REVID=147599068
alexjrosh · Feb 15, 2017 · 4f3b582 · 4f3b582
1 parent 81f92fe
commit 4f3b582
Show file tree

Hide file tree

Showing 4 changed files with 45 additions and 3 deletions.
diff --git a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
@@ -193,6 +193,9 @@ private static void collectBuiltinDoc(Map<String, SkylarkModuleDoc> modules, Fie
 
   private static Map<SkylarkModule, Class<?>> collectBuiltinJavaObjects(String ...clazz) {
     Map<SkylarkModule, Class<?>> modules = new HashMap<>();
+    collectBuiltinModule(modules, MethodLibrary.BoolModule.class);
+    collectBuiltinModule(modules, MethodLibrary.IntModule.class);
+
     collectBuiltinModule(modules, SkylarkRuleContext.class);
     collectBuiltinModule(modules, TransitiveInfoCollection.class);
 

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
@@ -47,7 +47,9 @@ protected String getTypeAnchor(Class<?> returnType, Class<?> generic1) {
 
   protected String getTypeAnchor(Class<?> type) {
     if (type.equals(Boolean.class) || type.equals(boolean.class)) {
-      return "<a class=\"anchor\" href=\"" + TOP_LEVEL_ID + ".html#bool\">bool</a>";
+      return "<a class=\"anchor\" href=\"bool.html\">bool</a>";
+    } else if (type.equals(int.class) || type.equals(Integer.class)) {
+      return "<a class=\"anchor\" href=\"int.html\">int</a>";
     } else if (type.equals(String.class)) {
       return "<a class=\"anchor\" href=\"string.html\">string</a>";
     } else if (Map.class.isAssignableFrom(type)) {

diff --git a/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java b/src/main/java/com/google/devtools/build/lib/syntax/MethodLibrary.java
@@ -2147,6 +2147,38 @@ public MutableList<?> invoke(SkylarkList<?> args, Location loc, Environment env)
   )
   static final class StringModule {}
 
+  /** Skylark int type. */
+  @SkylarkModule(
+    name = "int",
+    category = SkylarkModuleCategory.BUILTIN,
+    doc =
+        "A type to represent integers. It can represent any number between -2147483648 and "
+            + "2147483647 (included). "
+            + "Examples of int values:<br>"
+            + "<pre class=\"language-python\">"
+            + "153\n"
+            + "0x2A  # hexadecimal literal\n"
+            + "054  # octal literal\n"
+            + "23 * 2 + 5\n"
+            + "100 / -7\n"
+            + "100 % -7  # -5 (unlike in some other languages)\n"
+            + "int(\"18\")\n"
+            + "</pre>"
+  )
+  public static final class IntModule {}
+
+  /** Skylark bool type. */
+  @SkylarkModule(
+    name = "bool",
+    category = SkylarkModuleCategory.BUILTIN,
+    doc =
+        "A type to represent booleans. There are only two possible values: "
+            + "<a href=\"globals.html#True\">True</a> and "
+            + "<a href=\"globals.html#False\">False</a>. "
+            + "Any value can be converted to a boolean using the "
+            + "<a href=\"globals.html#bool\">bool</a> function."
+  )
+  public static final class BoolModule {}
 
   static final List<BaseFunction> defaultGlobalFunctions =
       ImmutableList.<BaseFunction>of(

diff --git a/src/test/java/com/google/devtools/build/docgen/SkylarkDocumentationTest.java b/src/test/java/com/google/devtools/build/docgen/SkylarkDocumentationTest.java
@@ -194,7 +194,11 @@ public void testSkylarkCallableParameters() throws Exception {
     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.getSignature())
+        .isEqualTo(
+            "<a class=\"anchor\" href=\"int.html\">int</a> "
+                + "MockClassD.test(arg0:<a class=\"anchor\" href=\"int.html\">int</a>, "
+                + "b, *, c, d=1)");
     assertThat(methodDoc.getParams()).hasSize(3);
   }
 
@@ -208,7 +212,8 @@ public void testSkylarkCallableOverriding() throws Exception {
     assertThat(moduleDoc.getMethods()).hasSize(1);
     SkylarkMethodDoc methodDoc = moduleDoc.getMethods().iterator().next();
     assertThat(methodDoc.getDocumentation()).isEqualTo("MockClassA#get");
-    assertThat(methodDoc.getSignature()).isEqualTo("int MockClassE.get()");
+    assertThat(methodDoc.getSignature())
+        .isEqualTo("<a class=\"anchor\" href=\"int.html\">int</a> MockClassE.get()");
   }
 
   private Iterable<Method> extractMethods(Collection<SkylarkJavaMethodDoc> methods) {