Create @SkylarkGlobalLibrary annotation, allowing classes/interfaces with global skylark functions to use @SkylarkCallable instead of @SkylarkSignature.

Also migrate skylark's global "rule" function to @SkylarkCallable, thus demonstrating the new feature.

RELNOTES: None.
PiperOrigin-RevId: 193085313

3 files changed, 51 insertions, 22 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
index cf892c92a8..0e2195f4ed 100644
--- a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
+++ b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
@@ -20,6 +20,7 @@ import com.google.devtools.build.docgen.skylark.SkylarkBuiltinMethodDoc;
 import com.google.devtools.build.docgen.skylark.SkylarkJavaMethodDoc;
 import com.google.devtools.build.docgen.skylark.SkylarkModuleDoc;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable;
+import com.google.devtools.build.lib.skylarkinterface.SkylarkGlobalLibrary;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkModule;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkModuleCategory;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkSignature;
@@ -76,11 +77,36 @@ final class SkylarkDocumentationCollector {
       if (annotation != null) {
         collectJavaObjects(annotation, candidateClass, modules);
       }
+      SkylarkGlobalLibrary
+          globalNamespaceAnnotation = candidateClass.getAnnotation(SkylarkGlobalLibrary.class);
+      if (globalNamespaceAnnotation != null) {
+        collectBuiltinMethods(modules, candidateClass);
+      }
       collectBuiltinDoc(modules, candidateClass.getDeclaredFields());
     }
     return modules;
   }
 
+  private static SkylarkModuleDoc getTopLevelModuleDoc(Map<String, SkylarkModuleDoc> modules) {
+    SkylarkModule annotation = getTopLevelModule();
+    modules.computeIfAbsent(
+        annotation.name(), (String k) -> new SkylarkModuleDoc(annotation, Object.class));
+    return modules.get(annotation.name());
+  }
+
+  private static SkylarkModuleDoc getSkylarkModuleDoc(
+      Class<?> moduleClass, Map<String, SkylarkModuleDoc> modules) {
+    if (moduleClass.equals(Object.class)) {
+      return getTopLevelModuleDoc(modules);
+    }
+
+    SkylarkModule annotation = Preconditions.checkNotNull(
+        Runtime.getSkylarkNamespace(moduleClass).getAnnotation(SkylarkModule.class));
+    modules.computeIfAbsent(
+        annotation.name(), (String k) -> new SkylarkModuleDoc(annotation, moduleClass));
+    return modules.get(annotation.name());
+  }
+
   /**
    * Collects and returns all the Java objects reachable in Skylark from (and including)
    * firstClass with the corresponding SkylarkModule annotation.
@@ -101,18 +127,14 @@ final class SkylarkDocumentationCollector {
 
     while (!toProcess.isEmpty()) {
       Class<?> c = toProcess.removeFirst();
-      SkylarkModule annotation = annotations.get(c);
-      done.add(c);
-      if (!modules.containsKey(annotation.name())) {
-        modules.put(annotation.name(), new SkylarkModuleDoc(annotation, c));
-      }
-      SkylarkModuleDoc module = modules.get(annotation.name());
+      SkylarkModuleDoc module = getSkylarkModuleDoc(c, modules);
 
       if (module.javaMethodsNotCollected()) {
         ImmutableMap<Method, SkylarkCallable> methods =
             FuncallExpression.collectSkylarkMethodsWithAnnotation(c);
         for (Map.Entry<Method, SkylarkCallable> entry : methods.entrySet()) {
-          module.addMethod(new SkylarkJavaMethodDoc(module, entry.getKey(), entry.getValue()));
+          module.addMethod(
+              new SkylarkJavaMethodDoc(module.getName(), entry.getKey(), entry.getValue()));
         }
 
         for (Map.Entry<Method, SkylarkCallable> method : methods.entrySet()) {
@@ -132,16 +154,22 @@ final class SkylarkDocumentationCollector {
       if (field.isAnnotationPresent(SkylarkSignature.class)) {
         SkylarkSignature skylarkSignature = field.getAnnotation(SkylarkSignature.class);
         Class<?> moduleClass = skylarkSignature.objectType();
-        SkylarkModule skylarkModule = moduleClass.equals(Object.class)
-            ? getTopLevelModule()
-            : Runtime.getSkylarkNamespace(moduleClass).getAnnotation(SkylarkModule.class);
-        Preconditions.checkNotNull(skylarkModule);
-        if (!modules.containsKey(skylarkModule.name())) {
-          modules.put(skylarkModule.name(), new SkylarkModuleDoc(skylarkModule, moduleClass));
-        }
-        SkylarkModuleDoc module = modules.get(skylarkModule.name());
+
+        SkylarkModuleDoc module = getSkylarkModuleDoc(moduleClass, modules);
         module.addMethod(new SkylarkBuiltinMethodDoc(module, skylarkSignature, field.getType()));
       }
     }
   }
+
+  private static void collectBuiltinMethods(
+      Map<String, SkylarkModuleDoc> modules, Class<?> moduleClass) {
+
+    SkylarkModuleDoc module = getTopLevelModuleDoc(modules);
+
+    ImmutableMap<Method, SkylarkCallable> methods =
+        FuncallExpression.collectSkylarkMethodsWithAnnotation(moduleClass);
+    for (Map.Entry<Method, SkylarkCallable> entry : methods.entrySet()) {
+      module.addMethod(new SkylarkJavaMethodDoc("", entry.getKey(), entry.getValue()));
+    }
+  }
 }
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 60ca32e093..614d155325 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
@@ -26,7 +26,7 @@ import java.util.List;
  * A class representing a Java method callable from Skylark with annotation.
  */
 public final class SkylarkJavaMethodDoc extends SkylarkMethodDoc {
-  private final SkylarkModuleDoc module;
+  private final String moduleName;
   private final String name;
   private final Method method;
   private final SkylarkCallable callable;
@@ -34,9 +34,8 @@ public final class SkylarkJavaMethodDoc extends SkylarkMethodDoc {
 
   private boolean isOverloaded;
 
-  public SkylarkJavaMethodDoc(SkylarkModuleDoc module, Method method,
-      SkylarkCallable callable) {
-    this.module = module;
+  public SkylarkJavaMethodDoc(String moduleName, Method method, SkylarkCallable callable) {
+    this.moduleName = moduleName;
     this.name = callable.name().isEmpty()
         ? StringUtilities.toPythonStyleFunctionName(method.getName())
         : callable.name();
@@ -88,7 +87,7 @@ public final class SkylarkJavaMethodDoc extends SkylarkMethodDoc {
 
   @Override
   public String getSignature() {
-    return getSignature(module.getName(), name, method);
+    return getSignature(moduleName, name, method);
   }
 
   @Override
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 daa365efbd..9fd398789b 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
@@ -82,11 +82,13 @@ public abstract class SkylarkMethodDoc extends SkylarkDoc {
   }
 
   protected String getSignature(String objectName, String methodName, Method method) {
+    String objectDotExpressionPrefix =
+        objectName.isEmpty() ? "" : objectName + ".";
     String args = SkylarkInterfaceUtils.getSkylarkCallable(method).structField()
         ? "" : "(" + getParameterString(method) + ")";
 
-    return String.format("%s %s.%s%s",
-        getTypeAnchor(method.getReturnType()), objectName, methodName, args);
+    return String.format("%s %s%s%s",
+        getTypeAnchor(method.getReturnType()), objectDotExpressionPrefix, methodName, args);
   }
 
   protected String getSignature(String objectName, SkylarkSignature method) {