Skip to content
Permalink
Browse files
8285939: javadoc java.lang.Record should not have "Direct Known Subcl…
…asses:" section

Reviewed-by: prappo, hannesw
  • Loading branch information
jonathan-gibbons committed May 31, 2022
1 parent f5bbade commit 8fc201e5bb7cb909a8bf496a751793b91b73631b
Showing 11 changed files with 316 additions and 296 deletions.
@@ -25,17 +25,19 @@

package jdk.javadoc.internal.doclets.formats.html;

import java.util.*;

import javax.lang.model.element.TypeElement;

import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
import jdk.javadoc.internal.doclets.formats.html.markup.TagName;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
import jdk.javadoc.internal.doclets.formats.html.markup.TagName;
import jdk.javadoc.internal.doclets.toolkit.Content;
import jdk.javadoc.internal.doclets.toolkit.util.ClassTree;
import jdk.javadoc.internal.doclets.toolkit.util.ClassTree.Hierarchy;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;

import javax.lang.model.element.TypeElement;
import java.util.Collection;
import java.util.SortedSet;
import java.util.TreeSet;


/**
* Abstract class to print the class hierarchy page for all the Classes. This
@@ -48,20 +50,19 @@ public abstract class AbstractTreeWriter extends HtmlDocletWriter {
/**
* The class and interface tree built by using {@link ClassTree}
*/
protected final ClassTree classtree;
protected final ClassTree classTree;

/**
* Constructor initializes classtree variable. This constructor will be used
* while generating global tree file "overview-tree.html".
* Constructor. This constructor will be used while generating global tree file "overview-tree.html".
*
* @param configuration The current configuration
* @param filename File to be generated.
* @param classtree Tree built by {@link ClassTree}.
* @param classTree Tree built by {@link ClassTree}.
*/
protected AbstractTreeWriter(HtmlConfiguration configuration,
DocPath filename, ClassTree classtree) {
DocPath filename, ClassTree classTree) {
super(configuration, filename);
this.classtree = classtree;
this.classTree = classTree;
}

/**
@@ -71,56 +72,48 @@ protected AbstractTreeWriter(HtmlConfiguration configuration,
*
* @param parent the superclass or superinterface of the sset
* @param collection a collection of the sub-classes at this level
* @param isEnum true if we are generating a tree for enums
* @param hierarchy the hierarchy for which we are generating a tree
* @param content the content to which the level information will be added
*/
protected void addLevelInfo(TypeElement parent, Collection<TypeElement> collection,
boolean isEnum, Content content) {
Hierarchy hierarchy, Content content) {
if (!collection.isEmpty()) {
var ul = new HtmlTree(TagName.UL);
for (TypeElement local : collection) {
var li = new HtmlTree(TagName.LI);
li.setStyle(HtmlStyle.circle);
addPartialInfo(local, li);
addExtendsImplements(parent, local, li);
addLevelInfo(local, classtree.directSubClasses(local, isEnum),
isEnum, li); // Recurse
addLevelInfo(local, hierarchy.subtypes(local), hierarchy, li); // Recurse
ul.add(li);
}
content.add(ul);
}
}

/**
* Add the heading for the tree depending upon tree type if it's a
* Class Tree or Interface tree.
* Adds a class or interface hierarchy with a given heading to given content.
*
* @param sset classes which are at the most base level, all the
* other classes in this run will derive from these classes
* @param heading heading for the tree
* @param content the content to which the tree will be added
* @param hierarchy the hierarchy to add
* @param heading the heading
* @param content the content to which to add the hierarchy
*/
protected void addTree(SortedSet<TypeElement> sset, String heading, Content content) {
addTree(sset, heading, content, false);
}

protected void addTree(SortedSet<TypeElement> sset, String heading,
Content content, boolean isEnums) {
if (!sset.isEmpty()) {
TypeElement firstTypeElement = sset.first();
protected void addTree(Hierarchy hierarchy, String heading, Content content) {
SortedSet<TypeElement> roots = hierarchy.roots();
if (!roots.isEmpty()) {
TypeElement firstTypeElement = roots.first();
Content headingContent = contents.getContent(heading);
var sectionHeading = HtmlTree.HEADING_TITLE(Headings.CONTENT_HEADING,
headingContent);
var section = HtmlTree.SECTION(HtmlStyle.hierarchy, sectionHeading);
addLevelInfo(!utils.isPlainInterface(firstTypeElement) ? firstTypeElement : null,
sset, isEnums, section);
roots, hierarchy, section);
content.add(section);
}
}

/**
* Add information regarding the classes which this class extends or
* implements.
* Add information regarding the classes which this class extends or implements.
*
* @param parent the parent class of the class being documented
* @param typeElement the TypeElement under consideration
@@ -143,11 +143,11 @@ public ClassUseWriter(HtmlConfiguration configuration,
* Write out class use pages.
*
* @param configuration the configuration for this doclet
* @param classtree the class tree hierarchy
* @param classTree the class tree hierarchy
* @throws DocFileIOException if there is an error while generating the documentation
*/
public static void generate(HtmlConfiguration configuration, ClassTree classtree) throws DocFileIOException {
ClassUseMapper mapper = new ClassUseMapper(configuration, classtree);
public static void generate(HtmlConfiguration configuration, ClassTree classTree) throws DocFileIOException {
ClassUseMapper mapper = new ClassUseMapper(configuration, classTree);
boolean nodeprecated = configuration.getOptions().noDeprecated();
Utils utils = configuration.utils;
for (TypeElement aClass : configuration.getIncludedTypeElements()) {
@@ -77,7 +77,7 @@ public class ClassWriterImpl extends SubWriterHolderWriter implements ClassWrite

protected final TypeElement typeElement;

protected final ClassTree classtree;
protected final ClassTree classTree;

/**
* @param configuration the configuration data for the doclet
@@ -89,7 +89,7 @@ public ClassWriterImpl(HtmlConfiguration configuration, TypeElement typeElement,
super(configuration, configuration.docPaths.forClass(typeElement));
this.typeElement = typeElement;
configuration.currentTypeElement = typeElement;
this.classtree = classTree;
this.classTree = classTree;
}

@Override
@@ -285,7 +285,7 @@ public void addSubClassInfo(Content target) {
return; // Don't generate the list, too huge
}
}
Set<TypeElement> subclasses = classtree.directSubClasses(typeElement, false);
Set<TypeElement> subclasses = classTree.hierarchy(typeElement).subtypes(typeElement);
if (!subclasses.isEmpty()) {
var dl = HtmlTree.DL(HtmlStyle.notes);
dl.add(HtmlTree.DT(contents.subclassesLabel));
@@ -298,7 +298,7 @@ public void addSubClassInfo(Content target) {
@Override
public void addSubInterfacesInfo(Content target) {
if (utils.isPlainInterface(typeElement)) {
Set<TypeElement> subInterfaces = classtree.allSubClasses(typeElement, false);
Set<TypeElement> subInterfaces = classTree.hierarchy(typeElement).allSubtypes(typeElement);
if (!subInterfaces.isEmpty()) {
var dl = HtmlTree.DL(HtmlStyle.notes);
dl.add(HtmlTree.DT(contents.subinterfacesLabel));
@@ -318,7 +318,7 @@ public void addInterfaceUsageInfo(Content target) {
return; // Don't generate the list, too huge
}
}
Set<TypeElement> implcl = classtree.implementingClasses(typeElement);
Set<TypeElement> implcl = classTree.implementingClasses(typeElement);
if (!implcl.isEmpty()) {
var dl = HtmlTree.DL(HtmlStyle.notes);
dl.add(HtmlTree.DT(contents.implementingClassesLabel));
@@ -203,9 +203,9 @@ public void generateClassFiles(ClassTree classTree) throws DocletException {
* @throws DocletException if there is a problem while writing the other files
*/
@Override // defined by AbstractDoclet
protected void generateOtherFiles(ClassTree classtree)
protected void generateOtherFiles(ClassTree classTree)
throws DocletException {
super.generateOtherFiles(classtree);
super.generateOtherFiles(classTree);
HtmlOptions options = configuration.getOptions();
if (options.linkSource()) {
SourceToHTMLConverter.convertRoot(configuration, DocPaths.SOURCE_OUTPUT);
@@ -228,11 +228,11 @@ protected void generateOtherFiles(ClassTree classtree)
}
// do early to reduce memory footprint
if (options.classUse()) {
ClassUseWriter.generate(configuration, classtree);
ClassUseWriter.generate(configuration, classTree);
}

if (options.createTree()) {
TreeWriter.generate(configuration, classtree);
TreeWriter.generate(configuration, classTree);
}

if (configuration.conditionalPages.contains((HtmlConfiguration.ConditionalPage.DEPRECATED))) {
@@ -392,7 +392,7 @@ protected void generateModuleFiles() throws DocletException {
}

@Override // defined by AbstractDoclet
protected void generatePackageFiles(ClassTree classtree) throws DocletException {
protected void generatePackageFiles(ClassTree classTree) throws DocletException {
HtmlOptions options = configuration.getOptions();
Set<PackageElement> packages = configuration.packages;
List<PackageElement> pList = new ArrayList<>(packages);
@@ -31,7 +31,6 @@
import jdk.javadoc.internal.doclets.formats.html.markup.BodyContents;
import jdk.javadoc.internal.doclets.formats.html.markup.ContentBuilder;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
import jdk.javadoc.internal.doclets.formats.html.markup.TagName;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
import jdk.javadoc.internal.doclets.toolkit.Content;
@@ -103,10 +102,11 @@ protected void generatePackageTreeFile() throws DocFileIOException {
addLinkToAllPackages(div);
}
mainContent.add(div);
addTree(classtree.baseClasses(), "doclet.Class_Hierarchy", mainContent);
addTree(classtree.baseInterfaces(), "doclet.Interface_Hierarchy", mainContent);
addTree(classtree.baseAnnotationTypes(), "doclet.Annotation_Type_Hierarchy", mainContent);
addTree(classtree.baseEnums(), "doclet.Enum_Hierarchy", mainContent, true);
addTree(classTree.classes(), "doclet.Class_Hierarchy", mainContent);
addTree(classTree.interfaces(), "doclet.Interface_Hierarchy", mainContent);
addTree(classTree.annotationInterfaces(), "doclet.Annotation_Type_Hierarchy", mainContent);
addTree(classTree.enumClasses(), "doclet.Enum_Hierarchy", mainContent);
addTree(classTree.recordClasses(), "doclet.Record_Class_Hierarchy", mainContent);
bodyContents.addMainContent(mainContent);
bodyContents.setFooter(getFooter());
body.add(bodyContents);
@@ -66,10 +66,10 @@ public class TreeWriter extends AbstractTreeWriter {
*
* @param configuration the current configuration of the doclet.
* @param filename String filename
* @param classtree the tree being built.
* @param classTree the tree being built.
*/
public TreeWriter(HtmlConfiguration configuration, DocPath filename, ClassTree classtree) {
super(configuration, filename, classtree);
public TreeWriter(HtmlConfiguration configuration, DocPath filename, ClassTree classTree) {
super(configuration, filename, classTree);
packages = configuration.packages;
classesOnly = packages.isEmpty();
this.bodyContents = new BodyContents();
@@ -80,13 +80,13 @@ public TreeWriter(HtmlConfiguration configuration, DocPath filename, ClassTree c
* "overview-tree.html" file.
*
* @param configuration the configuration for this doclet
* @param classtree the class tree being documented.
* @param classTree the class tree being documented.
* @throws DocFileIOException if there is a problem generating the overview tree page
*/
public static void generate(HtmlConfiguration configuration,
ClassTree classtree) throws DocFileIOException {
ClassTree classTree) throws DocFileIOException {
DocPath filename = DocPaths.OVERVIEW_TREE;
TreeWriter treegen = new TreeWriter(configuration, filename, classtree);
TreeWriter treegen = new TreeWriter(configuration, filename, classTree);
treegen.generateTreeFile();
}

@@ -104,10 +104,11 @@ public void generateTreeFile() throws DocFileIOException {
addPackageTreeLinks(div);
Content mainContent = new ContentBuilder();
mainContent.add(div);
addTree(classtree.baseClasses(), "doclet.Class_Hierarchy", mainContent);
addTree(classtree.baseInterfaces(), "doclet.Interface_Hierarchy", mainContent);
addTree(classtree.baseAnnotationTypes(), "doclet.Annotation_Type_Hierarchy", mainContent);
addTree(classtree.baseEnums(), "doclet.Enum_Hierarchy", mainContent, true);
addTree(classTree.classes(), "doclet.Class_Hierarchy", mainContent);
addTree(classTree.interfaces(), "doclet.Interface_Hierarchy", mainContent);
addTree(classTree.annotationInterfaces(), "doclet.Annotation_Type_Hierarchy", mainContent);
addTree(classTree.enumClasses(), "doclet.Enum_Hierarchy", mainContent);
addTree(classTree.recordClasses(), "doclet.Record_Class_Hierarchy", mainContent);
body.add(bodyContents
.addMainContent(mainContent)
.setFooter(getFooter()));
@@ -41,6 +41,7 @@ doclet.Window_Class_Hierarchy=Class Hierarchy
doclet.Interface_Hierarchy=Interface Hierarchy
doclet.Enum_Hierarchy=Enum Hierarchy
doclet.Enum_Class_Hierarchy=Enum Class Hierarchy
doclet.Record_Class_Hierarchy=Record Class Hierarchy
doclet.Annotation_Type_Hierarchy=Annotation Type Hierarchy
doclet.Annotation_Interface_Hierarchy=Annotation Interface Hierarchy
doclet.Href_Class_Title=class in {0}
@@ -202,25 +202,25 @@ private void startGeneration() throws DocletException {
}
messages.notice("doclet.build_version",
configuration.getDocletVersion());
ClassTree classtree = new ClassTree(configuration, configuration.getOptions().noDeprecated());
ClassTree classTree = new ClassTree(configuration);

generateClassFiles(classtree);
generateClassFiles(classTree);

ElementListWriter.generate(configuration);
generatePackageFiles(classtree);
generatePackageFiles(classTree);
generateModuleFiles();

generateOtherFiles(classtree);
generateOtherFiles(classTree);
configuration.tagletManager.printReport();
}

/**
* Generate additional documentation that is added to the API documentation.
*
* @param classtree the data structure representing the class tree
* @param classTree the data structure representing the class tree
* @throws DocletException if there is a problem while generating the documentation
*/
protected void generateOtherFiles(ClassTree classtree) throws DocletException {
protected void generateOtherFiles(ClassTree classTree) throws DocletException {
BuilderFactory builderFactory = configuration.getBuilderFactory();
AbstractBuilder constantsSummaryBuilder = builderFactory.getConstantsSummaryBuilder();
constantsSummaryBuilder.build();
@@ -239,28 +239,28 @@ protected void generateOtherFiles(ClassTree classtree) throws DocletException {
/**
* Generate the package documentation.
*
* @param classtree the data structure representing the class tree
* @param classTree the data structure representing the class tree
* @throws DocletException if there is a problem while generating the documentation
*/
protected abstract void generatePackageFiles(ClassTree classtree) throws DocletException;
protected abstract void generatePackageFiles(ClassTree classTree) throws DocletException;

/**
* Generate the class documentation.
*
* @param arr the set of types to be documented
* @param classtree the data structure representing the class tree
* @param classTree the data structure representing the class tree
* @throws DocletException if there is a problem while generating the documentation
*/
protected abstract void generateClassFiles(SortedSet<TypeElement> arr, ClassTree classtree)
protected abstract void generateClassFiles(SortedSet<TypeElement> arr, ClassTree classTree)
throws DocletException;

/**
* Iterate through all classes and construct documentation for them.
*
* @param classtree the data structure representing the class tree
* @param classTree the data structure representing the class tree
* @throws DocletException if there is a problem while generating the documentation
*/
protected void generateClassFiles(ClassTree classtree)
protected void generateClassFiles(ClassTree classTree)
throws DocletException {

SortedSet<TypeElement> classes = new TreeSet<>(utils.comparators.makeGeneralPurposeComparator());
@@ -278,6 +278,6 @@ protected void generateClassFiles(ClassTree classtree)
classes.addAll(utils.getAllClasses(pkg));
}

generateClassFiles(classes, classtree);
generateClassFiles(classes, classTree);
}
}

1 comment on commit 8fc201e

@openjdk-notifier
Copy link

@openjdk-notifier openjdk-notifier bot commented on 8fc201e May 31, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.