Skip to content
Permalink
Browse files
Automatic merge of jdk:master into master
  • Loading branch information
duke committed Mar 25, 2021
2 parents ec63b06 + a9d287a commit 3523cb75df586df1d6df31d5ce3206eae2ede27e
Showing 8 changed files with 357 additions and 1 deletion.
@@ -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");
@@ -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());
}
}
@@ -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
@@ -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.
*
@@ -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());
}
}
@@ -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
@@ -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;

0 comments on commit 3523cb7

Please sign in to comment.