stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
Reviewed-by: jjg
This commit is contained in:
Hannes Wallnöfer 2021-03-25 08:51:50 +00:00
parent 8120064dcc
commit a9d287a667
8 changed files with 357 additions and 1 deletions
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets
formats/html
Contents.javaPackageWriterImpl.java
markup
HtmlStyle.java
toolkit
PackageSummaryWriter.java
builders
PackageSummaryBuilder.java
resources
doclets.properties
util
Utils.java
test/langtools/jdk/javadoc/doclet/testRelatedPackages
TestRelatedPackages.java

2
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");

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

@ -162,6 +162,16 @@ public class PackageWriterImpl extends HtmlDocletWriter
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 class PackageWriterImpl extends HtmlDocletWriter
}
}
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 class PackageWriterImpl extends HtmlDocletWriter
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());
}
}

6
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

10
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.
*

58
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 @@ public class PackageSummaryBuilder extends AbstractBuilder {
protected void buildSummary(Content packageContentTree) throws DocletException {
Content summariesList = packageWriter.getSummariesList();
buildRelatedPackagesSummary(summariesList);
buildInterfaceSummary(summariesList);
buildClassSummary(summariesList);
buildEnumSummary(summariesList);
@ -157,6 +167,18 @@ public class PackageSummaryBuilder extends AbstractBuilder {
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 @@ public class PackageSummaryBuilder extends AbstractBuilder {
}
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());
}
}

1
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

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

@ -3175,7 +3175,7 @@ public class Utils {
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;

221
test/langtools/jdk/javadoc/doclet/testRelatedPackages/TestRelatedPackages.java Normal file

@ -0,0 +1,221 @@
/*
* Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/*
* @test
* @bug 8260388
* @summary Listing (sub)packages at package level of API documentation
* @library /tools/lib ../../lib
* @modules jdk.javadoc/jdk.javadoc.internal.tool
* @build toolbox.ToolBox javadoc.tester.*
* @run main TestRelatedPackages
*/
import toolbox.ModuleBuilder;
import toolbox.ToolBox;
import javadoc.tester.JavadocTester;
import java.nio.file.Path;
import java.nio.file.Paths;
public class TestRelatedPackages extends JavadocTester {
ToolBox tb = new ToolBox();
public static void main(String... args) throws Exception {
TestRelatedPackages tester = new TestRelatedPackages();
tester.runTests(m -> new Object[]{Paths.get(m.getName())});
}
@Test
public void testRelatedPackages(Path base) throws Exception {
Path src = base.resolve("src-packages");
tb.writeFile(src.resolve("p1/package-info.java"), "package p1;\n");
tb.writeFile(src.resolve("p1/s1/A.java"), "package p1.s1; public class A {}\n");
tb.writeFile(src.resolve("p1/s2/package-info.java"), "package p1.s1;\n");
tb.writeFile(src.resolve("p1/s3/B.java"), "package p1.s3; public class B {}\n");
tb.writeFile(src.resolve("p1/s3/t1/package-info.java"), "package p1.s3.t1;\n");
tb.writeFile(src.resolve("p1/s3/t2/C.java"), "package p1.s3.t2; public class C {}\n");
javadoc("-d", "out-packages",
"-sourcepath", src.toString(),
"-subpackages", "p1");
checkExit(Exit.OK);
checkOutput("p1/package-summary.html", true,
"""
<div class="caption"><span>Related Packages</span></div>
<div class="summary-table two-column-summary">
<div class="table-header col-first">Package</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color"><a href="s1/package-summary.html">p1.s1</a></div>
<div class="col-last even-row-color">&nbsp;</div>
<div class="col-first odd-row-color"><a href="s2/package-summary.html">p1.s2</a></div>
<div class="col-last odd-row-color">&nbsp;</div>
<div class="col-first even-row-color"><a href="s3/package-summary.html">p1.s3</a></div>
<div class="col-last even-row-color">&nbsp;</div>
</div>""");
checkOutput("p1/s1/package-summary.html", true,
"""
<div class="caption"><span>Related Packages</span></div>
<div class="summary-table two-column-summary">
<div class="table-header col-first">Package</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color"><a href="../package-summary.html">p1</a></div>
<div class="col-last even-row-color">&nbsp;</div>
<div class="col-first odd-row-color"><a href="../s2/package-summary.html">p1.s2</a></div>
<div class="col-last odd-row-color">&nbsp;</div>
<div class="col-first even-row-color"><a href="../s3/package-summary.html">p1.s3</a></div>
<div class="col-last even-row-color">&nbsp;</div>
</div>""");
checkOutput("p1/s2/package-summary.html", true,
"""
<div class="caption"><span>Related Packages</span></div>
<div class="summary-table two-column-summary">
<div class="table-header col-first">Package</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color"><a href="../package-summary.html">p1</a></div>
<div class="col-last even-row-color">&nbsp;</div>
<div class="col-first odd-row-color"><a href="../s1/package-summary.html">p1.s1</a></div>
<div class="col-last odd-row-color">&nbsp;</div>
<div class="col-first even-row-color"><a href="../s3/package-summary.html">p1.s3</a></div>
<div class="col-last even-row-color">&nbsp;</div>
</div>""");
checkOutput("p1/s3/package-summary.html", true,
"""
<div class="caption"><span>Related Packages</span></div>
<div class="summary-table two-column-summary">
<div class="table-header col-first">Package</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color"><a href="../package-summary.html">p1</a></div>
<div class="col-last even-row-color">&nbsp;</div>
<div class="col-first odd-row-color"><a href="t1/package-summary.html">p1.s3.t1</a></div>
<div class="col-last odd-row-color">&nbsp;</div>
<div class="col-first even-row-color"><a href="t2/package-summary.html">p1.s3.t2</a></div>
<div class="col-last even-row-color">&nbsp;</div>
<div class="col-first odd-row-color"><a href="../s1/package-summary.html">p1.s1</a></div>
<div class="col-last odd-row-color">&nbsp;</div>
<div class="col-first even-row-color"><a href="../s2/package-summary.html">p1.s2</a></div>
<div class="col-last even-row-color">&nbsp;</div>
</div>""");
checkOutput("p1/s3/t1/package-summary.html", true,
"""
<div class="caption"><span>Related Packages</span></div>
<div class="summary-table two-column-summary">
<div class="table-header col-first">Package</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color"><a href="../package-summary.html">p1.s3</a></div>
<div class="col-last even-row-color">&nbsp;</div>
<div class="col-first odd-row-color"><a href="../t2/package-summary.html">p1.s3.t2</a></div>
<div class="col-last odd-row-color">&nbsp;</div>
</div>""");
checkOutput("p1/s3/t2/package-summary.html", true,
"""
<div class="caption"><span>Related Packages</span></div>
<div class="summary-table two-column-summary">
<div class="table-header col-first">Package</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color"><a href="../package-summary.html">p1.s3</a></div>
<div class="col-last even-row-color">&nbsp;</div>
<div class="col-first odd-row-color"><a href="../t1/package-summary.html">p1.s3.t1</a></div>
<div class="col-last odd-row-color">&nbsp;</div>
</div>""");
}
@Test
public void testCrossModuleRelatedPackages(Path base) throws Exception {
Path src = base.resolve("src-modules");
new ModuleBuilder(tb, "m")
.exports("pkg")
.exports("pkg.sub1")
.classes("package pkg; public class A { }",
"package pkg.sub1; public class B { }")
.write(src);
new ModuleBuilder(tb, "o")
.exports("pkg.sub2")
.exports("pkg.sub2.sub")
.classes("package pkg.sub2; public class C { }",
"package pkg.sub2.sub; public class D { }")
.write(src);
javadoc("-d", "out-modules",
"-quiet",
"--module-source-path", src.toString(),
"--module", "m,o");
checkExit(Exit.OK);
checkOutput("m/pkg/package-summary.html", true,
"""
<div class="caption"><span>Related Packages</span></div>
<div class="summary-table three-column-summary">
<div class="table-header col-first">Module</div>
<div class="table-header col-second">Package</div>
<div class="table-header col-last">Description</div>
<div class="col-plain even-row-color"><a href="../module-summary.html">m</a></div>
<div class="col-first even-row-color"><a href="sub1/package-summary.html">pkg.sub1</a></div>
<div class="col-last even-row-color">&nbsp;</div>
<div class="col-plain odd-row-color"><a href="../../o/module-summary.html">o</a></div>
<div class="col-first odd-row-color"><a href="../../o/pkg/sub2/package-summary.html">pkg.sub2</a></div>
<div class="col-last odd-row-color">&nbsp;</div>
</div>""");
checkOutput("m/pkg/sub1/package-summary.html", true,
"""
<div class="caption"><span>Related Packages</span></div>
<div class="summary-table three-column-summary">
<div class="table-header col-first">Module</div>
<div class="table-header col-second">Package</div>
<div class="table-header col-last">Description</div>
<div class="col-plain even-row-color"><a href="../../module-summary.html">m</a></div>
<div class="col-first even-row-color"><a href="../package-summary.html">pkg</a></div>
<div class="col-last even-row-color">&nbsp;</div>
<div class="col-plain odd-row-color"><a href="../../../o/module-summary.html">o</a></div>
<div class="col-first odd-row-color"><a href="../../../o/pkg/sub2/package-summary.html">pkg.sub2</a></div>
<div class="col-last odd-row-color">&nbsp;</div>
</div>""");
checkOutput("o/pkg/sub2/package-summary.html", true,
"""
<div class="caption"><span>Related Packages</span></div>
<div class="summary-table three-column-summary">
<div class="table-header col-first">Module</div>
<div class="table-header col-second">Package</div>
<div class="table-header col-last">Description</div>
<div class="col-plain even-row-color"><a href="../../../m/module-summary.html">m</a></div>
<div class="col-first even-row-color"><a href="../../../m/pkg/package-summary.html">pkg</a></div>
<div class="col-last even-row-color">&nbsp;</div>
<div class="col-plain odd-row-color"><a href="../../module-summary.html">o</a></div>
<div class="col-first odd-row-color"><a href="sub/package-summary.html">pkg.sub2.sub</a></div>
<div class="col-last odd-row-color">&nbsp;</div>
<div class="col-plain even-row-color"><a href="../../../m/module-summary.html">m</a></div>
<div class="col-first even-row-color"><a href="../../../m/pkg/sub1/package-summary.html">pkg.sub1</a></div>
<div class="col-last even-row-color">&nbsp;</div>
</div>""");
checkOutput("o/pkg/sub2/sub/package-summary.html", true,
"""
<div class="caption"><span>Related Packages</span></div>
<div class="summary-table two-column-summary">
<div class="table-header col-first">Package</div>
<div class="table-header col-last">Description</div>
<div class="col-first even-row-color"><a href="../package-summary.html">pkg.sub2</a></div>
<div class="col-last even-row-color">&nbsp;</div>
</div>""");
}
}