Fix docgen handling of multiple modules with the same name

If there are multiple modules with the same name:
  - If only one is marked 'documented', that one takes precedence.
  - If one is a subclass of the others, the subclass takes precedence.
  - Otherwise, an exception is thrown.

RELNOTES: None.
PiperOrigin-RevId: 202359443

1 files changed, 26 insertions, 5 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 884fe299e7..0704c3888f 100644
--- a/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
+++ b/src/main/java/com/google/devtools/build/docgen/SkylarkDocumentationCollector.java
@@ -89,7 +89,7 @@ final class SkylarkDocumentationCollector {
   private static SkylarkModuleDoc getTopLevelModuleDoc(Map<String, SkylarkModuleDoc> modules) {
     SkylarkModule annotation = getTopLevelModule();
     modules.computeIfAbsent(
-        annotation.name(), (String k) -> new SkylarkModuleDoc(annotation, Object.class));
+        annotation.name(), (String k) -> new SkylarkModuleDoc(annotation, TopLevelModule.class));
     return modules.get(annotation.name());
   }
 
@@ -101,8 +101,29 @@ final class SkylarkDocumentationCollector {
 
     SkylarkModule annotation = Preconditions.checkNotNull(
         Runtime.getSkylarkNamespace(moduleClass).getAnnotation(SkylarkModule.class));
-    modules.computeIfAbsent(
-        annotation.name(), (String k) -> new SkylarkModuleDoc(annotation, moduleClass));
+    SkylarkModuleDoc previousModuleDoc = modules.get(annotation.name());
+    if (previousModuleDoc == null || !previousModuleDoc.getAnnotation().documented()) {
+      // There is no registered module doc by that name, or the current candidate is "undocumented".
+      modules.put(annotation.name(), new SkylarkModuleDoc(annotation, moduleClass));
+    } else if (previousModuleDoc.getClassObject() != moduleClass && annotation.documented()) {
+      // Both modules generate documentation for the same name. This is fine if one is a
+      // subclass of the other, in which case the subclass documentation takes precedence.
+      // (This is useful if one module is a "common" stable module, and its subclass is
+      // an experimental module that also supports all stable methods.)
+      if (previousModuleDoc.getClassObject().isAssignableFrom(moduleClass)) {
+        modules.put(annotation.name(), new SkylarkModuleDoc(annotation, moduleClass));
+      } else if (moduleClass.isAssignableFrom(previousModuleDoc.getClassObject())) {
+        // This case means the subclass was processed first, so discard the superclass.
+      } else {
+        throw new IllegalStateException(
+            String.format(
+                "%s and %s are both modules with the same documentation for '%s'",
+                moduleClass,
+                previousModuleDoc.getClassObject(),
+                previousModuleDoc.getAnnotation().name()));
+      }
+    }
+
     return modules.get(annotation.name());
   }
 
@@ -225,14 +246,14 @@ final class SkylarkDocumentationCollector {
     if (!constructorAnnotation.receiverNameForDoc().isEmpty()) {
       fullyQualifiedName = constructorAnnotation.receiverNameForDoc();
     } else {
-      fullyQualifiedName = getFullyQualifiedName(originatingModuleName, method, callable);
+      fullyQualifiedName = getFullyQualifiedName(originatingModuleName, callable);
     }
 
     module.setConstructor(new SkylarkConstructorMethodDoc(fullyQualifiedName, method, callable));
   }
 
   private static String getFullyQualifiedName(
-      String objectName, Method method, SkylarkCallable callable) {
+      String objectName, SkylarkCallable callable) {
     String objectDotExpressionPrefix = objectName.isEmpty() ? "" : objectName + ".";
     String methodName = callable.name();
     return objectDotExpressionPrefix + methodName;