Migrate JavaInfo's provider to use the new provider pattern.

This dramatically improves documentation generation for JavaInfo and it makes it far more maintainable and extensible going forward.

RELNOTES: None.
PiperOrigin-RevId: 197619040

4 files changed, 125 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 67c46f0e95..6d38c43c3f 100644
--- a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
+++ b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
@@ -17,6 +17,7 @@ import com.google.common.annotations.VisibleForTesting;
 import com.google.common.base.Preconditions;
 import com.google.common.collect.ImmutableMap;
 import com.google.devtools.build.docgen.skylark.SkylarkBuiltinMethodDoc;
+import com.google.devtools.build.docgen.skylark.SkylarkConstructorMethodDoc;
 import com.google.devtools.build.docgen.skylark.SkylarkJavaMethodDoc;
 import com.google.devtools.build.docgen.skylark.SkylarkModuleDoc;
 import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable;
@@ -29,6 +30,7 @@ import com.google.devtools.build.lib.syntax.FuncallExpression;
 import com.google.devtools.build.lib.syntax.Runtime;
 import com.google.devtools.build.lib.util.Classpath;
 import com.google.devtools.build.lib.util.Classpath.ClassPathException;
+import com.google.devtools.build.lib.util.StringUtilities;
 import java.lang.reflect.Field;
 import java.lang.reflect.Method;
 import java.util.ArrayDeque;
@@ -74,13 +76,10 @@ final class SkylarkDocumentationCollector {
       throws ClassPathException {
     Map<String, SkylarkModuleDoc> modules = new TreeMap<>();
     for (Class<?> candidateClass : Classpath.findClasses(MODULES_PACKAGE_PREFIX)) {
-      SkylarkModule annotation = candidateClass.getAnnotation(SkylarkModule.class);
-      if (annotation != null) {
-        collectJavaObjects(annotation, candidateClass, modules);
-      }
-      SkylarkGlobalLibrary
-          globalNamespaceAnnotation = candidateClass.getAnnotation(SkylarkGlobalLibrary.class);
-      if (globalNamespaceAnnotation != null) {
+      SkylarkModule moduleAnnotation = candidateClass.getAnnotation(SkylarkModule.class);
+      if (moduleAnnotation != null) {
+        collectJavaObjects(moduleAnnotation, candidateClass, modules);
+      } else if (candidateClass.getAnnotation(SkylarkGlobalLibrary.class) != null) {
         collectBuiltinMethods(modules, candidateClass);
       }
       collectBuiltinDoc(modules, candidateClass.getDeclaredFields());
@@ -222,6 +221,24 @@ final class SkylarkDocumentationCollector {
         Preconditions.checkNotNull(method.getAnnotation(SkylarkConstructor.class));
     Class<?> objectClass = constructorAnnotation.objectType();
     SkylarkModuleDoc module = getSkylarkModuleDoc(objectClass, modules);
-    module.setConstructor(new SkylarkJavaMethodDoc(originatingModuleName, method, callable));
+
+    String fullyQualifiedName;
+    if (!constructorAnnotation.receiverNameForDoc().isEmpty()) {
+      fullyQualifiedName = constructorAnnotation.receiverNameForDoc();
+    } else {
+      fullyQualifiedName = getFullyQualifiedName(originatingModuleName, method, callable);
+    }
+
+    module.setConstructor(new SkylarkConstructorMethodDoc(fullyQualifiedName, method, callable));
+  }
+
+  private static String getFullyQualifiedName(
+      String objectName, Method method, SkylarkCallable callable) {
+    String objectDotExpressionPrefix =
+      objectName.isEmpty() ? "" : objectName + ".";
+    String methodName = callable.name().isEmpty()
+        ? StringUtilities.toPythonStyleFunctionName(method.getName())
+        : callable.name();
+    return objectDotExpressionPrefix + methodName;
   }
 }
diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkConstructorMethodDoc.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkConstructorMethodDoc.java
new file mode 100644
index 0000000000..c2491913c7
--- /dev/null
+++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkConstructorMethodDoc.java
@@ -0,0 +1,78 @@
+// Copyright 2018 The Bazel Authors. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+package com.google.devtools.build.docgen.skylark;
+
+import com.google.common.collect.ImmutableList;
+import com.google.devtools.build.lib.skylarkinterface.SkylarkCallable;
+import java.lang.reflect.Method;
+import java.util.List;
+
+/**
+ * A class representing a Java method callable from Skylark which constructs a type of
+ * skylark object. Such a method is annotated with {@link SkylarkConstructor}, and has special
+ * handling.
+ */
+public final class SkylarkConstructorMethodDoc extends SkylarkMethodDoc {
+  private final String fullyQualifiedName;
+  private final Method method;
+  private final SkylarkCallable callable;
+  private final ImmutableList<SkylarkParamDoc> params;
+
+  public SkylarkConstructorMethodDoc(
+      String fullyQualifiedName, Method method, SkylarkCallable callable) {
+    this.fullyQualifiedName = fullyQualifiedName;
+    this.method = method;
+    this.callable = callable;
+    this.params =
+        SkylarkDocUtils.determineParams(
+            this, callable.parameters(), callable.extraPositionals(), callable.extraKeywords());
+  }
+
+  public Method getMethod() {
+    return method;
+  }
+
+  @Override
+  public boolean documented() {
+    return callable.documented();
+  }
+
+  @Override
+  public String getName() {
+    return fullyQualifiedName;
+  }
+
+  @Override
+  public String getDocumentation() {
+    return SkylarkDocUtils.substituteVariables(callable.doc());
+  }
+
+  @Override
+  public String getSignature() {
+    return getSignature(fullyQualifiedName, method);
+  }
+
+  @Override
+  public String getReturnTypeExtraMessage() {
+    if (callable.allowReturnNones()) {
+      return " May return <code>None</code>.\n";
+    }
+    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 9fd398789b..293c56e863 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
@@ -31,12 +31,6 @@ public abstract class SkylarkMethodDoc extends SkylarkDoc {
   public abstract boolean documented();
 
   /**
-   * Returns a string representing the method signature of the Skylark method, which contains
-   * HTML links to the documentation of parameter types if available.
-   */
-  public abstract String getSignature();
-
-  /**
    * Returns a string containing additional documentation about the method's return value.
    *
    * <p>Returns an empty string by default.
@@ -81,14 +75,25 @@ public abstract class SkylarkMethodDoc extends SkylarkDoc {
     return Joiner.on(", ").join(argList);
   }
 
+  /**
+   * Returns a string representing the method signature of the Skylark method, which contains
+   * HTML links to the documentation of parameter types if available.
+   */
+  public abstract String getSignature();
+
   protected String getSignature(String objectName, String methodName, Method method) {
     String objectDotExpressionPrefix =
         objectName.isEmpty() ? "" : objectName + ".";
+
+    return getSignature(objectDotExpressionPrefix + methodName, method);
+  }
+
+  protected String getSignature(String fullyQualifiedMethodName, Method method) {
     String args = SkylarkInterfaceUtils.getSkylarkCallable(method).structField()
         ? "" : "(" + getParameterString(method) + ")";
 
-    return String.format("%s %s%s%s",
-        getTypeAnchor(method.getReturnType()), objectDotExpressionPrefix, methodName, args);
+    return String.format("%s %s%s",
+        getTypeAnchor(method.getReturnType()), fullyQualifiedMethodName, args);
   }
 
   protected String getSignature(String objectName, SkylarkSignature method) {
diff --git a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkModuleDoc.java b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkModuleDoc.java
index 24da2f3e96..bdac30a12e 100644
--- a/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkModuleDoc.java
+++ b/src/main/java/com/google/devtools/build/docgen/skylark/SkylarkModuleDoc.java
@@ -40,7 +40,7 @@ public final class SkylarkModuleDoc extends SkylarkDoc {
   private final Multimap<String, SkylarkJavaMethodDoc> javaMethods;
   private TreeMap<String, SkylarkMethodDoc> methodMap;
   private final String title;
-  @Nullable private SkylarkJavaMethodDoc javaConstructor;
+  @Nullable private SkylarkConstructorMethodDoc javaConstructor;
 
   public SkylarkModuleDoc(SkylarkModule module, Class<?> classObject) {
     this.module = Preconditions.checkNotNull(
@@ -78,10 +78,9 @@ public final class SkylarkModuleDoc extends SkylarkDoc {
     return classObject;
   }
 
-  public void setConstructor(SkylarkJavaMethodDoc method) {
+  public void setConstructor(SkylarkConstructorMethodDoc method) {
     Preconditions.checkState(javaConstructor == null);
     javaConstructor = method;
-    methodMap.put(method.getName(), method);
   }
 
   public void addMethod(SkylarkBuiltinMethodDoc method) {
@@ -123,8 +122,8 @@ public final class SkylarkModuleDoc extends SkylarkDoc {
     return builtinMethodMap;
   }
 
-  public Collection<SkylarkJavaMethodDoc> getJavaMethods() {
-    ImmutableList.Builder<SkylarkJavaMethodDoc> returnedMethods = ImmutableList.builder();
+  public Collection<SkylarkMethodDoc> getJavaMethods() {
+    ImmutableList.Builder<SkylarkMethodDoc> returnedMethods = ImmutableList.builder();
     if (javaConstructor != null) {
       returnedMethods.add(javaConstructor);
     }
@@ -132,6 +131,10 @@ public final class SkylarkModuleDoc extends SkylarkDoc {
   }
 
   public Collection<SkylarkMethodDoc> getMethods() {
-    return methodMap.values();
+    ImmutableList.Builder<SkylarkMethodDoc> methods = ImmutableList.builder();
+    if (javaConstructor != null) {
+      methods.add(javaConstructor);
+    }
+    return methods.addAll(methodMap.values()).build();
   }
 }