8260388: Listing (sub)packages at package level of API documentation

Reviewed-by: jjg

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Contents.java

@@ -162,6 +162,7 @@ public class Contents {
     public final Content record;
     public final Content recordComponents;
     public final Content referencedIn;
+    public final Content relatedPackages;
     public final Content returns;
     public final Content seeAlso;
     public final Content serializedForm;
@@ -311,6 +312,7 @@ public class Contents {
         record = getContent("doclet.RecordClass");
         recordComponents = getContent("doclet.RecordComponents");
         referencedIn = getContent("doclet.ReferencedIn");
+        relatedPackages = getContent("doclet.Related_Packages");
         returns = getContent("doclet.Returns");
         seeAlso = getContent("doclet.See_Also");
         serializedForm = getContent("doclet.Serialized_Form");

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriterImpl.java

@@ -162,6 +162,16 @@ public Content getSummariesList() {
         return new HtmlTree(TagName.UL).setStyle(HtmlStyle.summaryList);
     }
 
+    @Override
+    public void addRelatedPackagesSummary(List<PackageElement> relatedPackages, Content summaryContentTree) {
+        boolean showModules = configuration.showModules && hasRelatedPackagesInOtherModules(relatedPackages);
+        TableHeader tableHeader= showModules
+                ? new TableHeader(contents.moduleLabel, contents.packageLabel, contents.descriptionLabel)
+                : new TableHeader(contents.packageLabel, contents.descriptionLabel);
+        addPackageSummary(relatedPackages, contents.relatedPackages, tableHeader,
+                summaryContentTree, showModules);
+    }
+
     @Override
     public void addInterfaceSummary(SortedSet<TypeElement> interfaces, Content summaryContentTree) {
         TableHeader tableHeader= new TableHeader(contents.interfaceLabel, contents.descriptionLabel);
@@ -235,6 +245,49 @@ public void addClassesSummary(SortedSet<TypeElement> classes, String label,
         }
     }
 
+    public void addPackageSummary(List<PackageElement> packages, Content label,
+                                  TableHeader tableHeader, Content summaryContentTree,
+                                  boolean showModules) {
+        if (!packages.isEmpty()) {
+            Table table = new Table(HtmlStyle.summaryTable)
+                    .setCaption(label)
+                    .setHeader(tableHeader);
+            if (showModules) {
+                table.setColumnStyles(HtmlStyle.colPlain, HtmlStyle.colFirst, HtmlStyle.colLast);
+            } else {
+                table.setColumnStyles(HtmlStyle.colFirst, HtmlStyle.colLast);
+            }
+
+            for (PackageElement pkg : packages) {
+                Content packageLink = getPackageLink(pkg, Text.of(pkg.getQualifiedName()));
+                Content moduleLink = HtmlTree.EMPTY;
+                if (showModules) {
+                    ModuleElement module = (ModuleElement) pkg.getEnclosingElement();
+                    if (module != null && !module.isUnnamed()) {
+                        moduleLink = getModuleLink(module, Text.of(module.getQualifiedName()));
+                    }
+                }
+                ContentBuilder description = new ContentBuilder();
+                addPreviewSummary(pkg, description);
+                if (utils.isDeprecated(pkg)) {
+                    description.add(getDeprecatedPhrase(pkg));
+                    List<? extends DeprecatedTree> tags = utils.getDeprecatedTrees(pkg);
+                    if (!tags.isEmpty()) {
+                        addSummaryDeprecatedComment(pkg, tags.get(0), description);
+                    }
+                } else {
+                    addSummaryComment(pkg, description);
+                }
+                if (showModules) {
+                    table.addRow(moduleLink, packageLink, description);
+                } else {
+                    table.addRow(packageLink, description);
+                }
+            }
+            summaryContentTree.add(HtmlTree.LI(table));
+        }
+    }
+
     @Override
     public void addPackageDescription(Content packageContentTree) {
         addPreviewInfo(packageElement, packageContentTree);
@@ -282,4 +335,9 @@ public void printDocument(Content contentTree) throws DocFileIOException {
     public Content getPackageSummary(Content summaryContentTree) {
         return HtmlTree.SECTION(HtmlStyle.summary, summaryContentTree);
     }
+
+    private boolean hasRelatedPackagesInOtherModules(List<PackageElement> relatedPackages) {
+        final ModuleElement module = (ModuleElement) packageElement.getEnclosingElement();
+        return relatedPackages.stream().anyMatch(pkg -> module != pkg.getEnclosingElement());
+    }
 }

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java

@@ -438,6 +438,12 @@ public enum HtmlStyle {
      */
     colSummaryItemName,
 
+    /**
+     * The class of the cells in a table column used to display additional
+     * information without any particular style.
+     */
+    colPlain,
+
     /**
      * The class of the second column of cells in a table.
      * This is typically the column that defines the name of a field or the

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/PackageSummaryWriter.java

@@ -25,8 +25,10 @@
 
 package jdk.javadoc.internal.doclets.toolkit;
 
+import java.util.List;
 import java.util.SortedSet;
 
+import javax.lang.model.element.PackageElement;
 import javax.lang.model.element.TypeElement;
 
 import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
@@ -63,6 +65,14 @@ public interface PackageSummaryWriter {
      */
     Content getSummariesList();
 
+    /**
+     * Adds the table of related packages to the documentation tree.
+     *
+     * @param relatedPackages the interfaces to document.
+     * @param summaryContentTree the content tree to which the summaries will be added
+     */
+    void addRelatedPackagesSummary(List<PackageElement> relatedPackages, Content summaryContentTree);
+
     /**
      * Adds the table of interfaces to the documentation tree.
      *

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/PackageSummaryBuilder.java

@@ -25,8 +25,13 @@
 
 package jdk.javadoc.internal.doclets.toolkit.builders;
 
+import java.util.ArrayList;
+import java.util.List;
 import java.util.Set;
 import java.util.SortedSet;
+import java.util.function.Predicate;
+import java.util.regex.Pattern;
+import java.util.stream.Collectors;
 
 import javax.lang.model.element.PackageElement;
 import javax.lang.model.element.TypeElement;
@@ -57,6 +62,10 @@ public class PackageSummaryBuilder extends AbstractBuilder {
      */
     private final PackageSummaryWriter packageWriter;
 
+    // Maximum number of subpackages and sibling packages to list in related packages table
+    private final static int MAX_SUBPACKAGES = 20;
+    private final static int MAX_SIBLING_PACKAGES = 5;
+
     /**
      * Construct a new PackageSummaryBuilder.
      *
@@ -146,6 +155,7 @@ protected void buildContent() throws DocletException {
     protected void buildSummary(Content packageContentTree) throws DocletException {
         Content summariesList = packageWriter.getSummariesList();
 
+        buildRelatedPackagesSummary(summariesList);
         buildInterfaceSummary(summariesList);
         buildClassSummary(summariesList);
         buildEnumSummary(summariesList);
@@ -157,6 +167,18 @@ protected void buildSummary(Content packageContentTree) throws DocletException {
         packageContentTree.add(packageWriter.getPackageSummary(summariesList));
     }
 
+    /**
+     * Builds a list of "nearby" packages (subpackages, super and sibling packages).
+     *
+     * @param summariesList the list of summaries to which the summary will be added
+     */
+    protected void buildRelatedPackagesSummary(Content summariesList) {
+        List<PackageElement> packages = findRelatedPackages();
+        if (!packages.isEmpty()) {
+            packageWriter.addRelatedPackagesSummary(packages, summariesList);
+        }
+    }
+
     /**
      * Builds the summary for any interfaces in this package.
      *
@@ -291,4 +313,40 @@ protected void buildPackageTags(Content packageContentTree) {
         }
         packageWriter.addPackageTags(packageContentTree);
     }
+
+    private List<PackageElement> findRelatedPackages() {
+        String pkgName = packageElement.getQualifiedName().toString();
+
+        // always add super package
+        int lastdot = pkgName.lastIndexOf('.');
+        String pkgPrefix = lastdot > 0 ? pkgName.substring(0, lastdot) : null;
+        List<PackageElement> packages = new ArrayList<>(
+                filterPackages(p -> p.getQualifiedName().toString().equals(pkgPrefix)));
+
+        // add subpackages unless there are very many of them
+        Pattern subPattern = Pattern.compile(pkgName.replace(".", "\\.") + "\\.\\w+");
+        List<PackageElement> subpackages = filterPackages(
+                p -> subPattern.matcher(p.getQualifiedName().toString()).matches());
+        if (subpackages.size() <= MAX_SUBPACKAGES) {
+            packages.addAll(subpackages);
+        }
+
+        // only add sibling packages if we are beneath threshold, and number of siblings is beneath threshold as well
+        if (pkgPrefix != null && packages.size() <= MAX_SIBLING_PACKAGES) {
+            Pattern siblingPattern = Pattern.compile(pkgPrefix.replace(".", "\\.") + "\\.\\w+");
+
+            List<PackageElement> siblings = filterPackages(
+                    p -> siblingPattern.matcher(p.getQualifiedName().toString()).matches());
+            if (siblings.size() <= MAX_SIBLING_PACKAGES) {
+                packages.addAll(siblings);
+            }
+        }
+        return packages;
+    }
+
+    private List<PackageElement> filterPackages(Predicate<? super PackageElement> filter) {
+        return configuration.packages.stream()
+                .filter(p -> p != packageElement && filter.test(p))
+                .collect(Collectors.toList());
+    }
 }

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/doclets.properties

@@ -133,6 +133,7 @@ doclet.Exception_Summary=Exception Summary
 doclet.Error_Summary=Error Summary
 doclet.Class_Summary=Class Summary
 doclet.Nested_Class_Summary=Nested Class Summary
+doclet.Related_Packages=Related Packages
 doclet.Annotation_Type_Optional_Member_Summary=Optional Element Summary
 doclet.Annotation_Type_Required_Member_Summary=Required Element Summary
 doclet.Field_Summary=Field Summary

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java

@@ -3175,7 +3175,7 @@ public boolean isPreviewAPI(Element el) {
         boolean parentPreviewAPI = false;
         Element enclosing = el.getEnclosingElement();
         if (enclosing != null && (enclosing.getKind().isClass() || enclosing.getKind().isInterface())) {
-            parentPreviewAPI = configuration.workArounds.isPreviewAPI(el.getEnclosingElement());
+            parentPreviewAPI = configuration.workArounds.isPreviewAPI(enclosing);
         }
         boolean previewAPI = configuration.workArounds.isPreviewAPI(el);
         return !parentPreviewAPI && previewAPI;