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

8313349: Introduce abstract void HtmlDocletWriter.buildPage()

Browse Source 
Reviewed-by: prappo
This commit is contained in:
Jonathan Gibbons 2023-08-02 21:59:22 +00:00
parent bc1d2eac9a
commit 6d180d5fbf
46 changed files with 763 additions and 842 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractExecutableMemberWriter.java
View File

@ -52,20 +52,38 @@ import static jdk.javadoc.internal.doclets.formats.html.HtmlLinkInfo.Kind.SHOW_P
import static jdk.javadoc.internal.doclets.formats.html.HtmlLinkInfo.Kind.SHOW_TYPE_PARAMS_AND_BOUNDS;
/**
* Print method and constructor info.
* Abstract "member writer" for executable elements.
*/
public abstract class AbstractExecutableMemberWriter extends AbstractMemberWriter {
public AbstractExecutableMemberWriter(SubWriterHolderWriter writer, TypeElement typeElement,
/**
* Creates a writer for executable members, for a given enclosing writer, type element, and kind of member.
*
* @param writer the enclosing "page" writer, with an associated type element
* @param typeElement the type element
* @param kind the kind of member: one of {@link VisibleMemberTable.Kind#CONSTRUCTORS} or {@link VisibleMemberTable.Kind#METHODS}
*/
protected AbstractExecutableMemberWriter(SubWriterHolderWriter writer, TypeElement typeElement,
VisibleMemberTable.Kind kind) {
super(writer, typeElement, kind);
// The following would be better before the preceding call to super; see JDK-8300786
switch (kind) {
case CONSTRUCTORS, METHODS -> { }
default -> throw new IllegalArgumentException(kind.toString());
}
}
public AbstractExecutableMemberWriter(SubWriterHolderWriter writer) {
/**
* Creates a writer for executable members, for a given enclosing writer.
* No type element or kind is provided, limiting the set of methods that can be used.
*
* @param writer the enclosing "page" writer.
*/
protected AbstractExecutableMemberWriter(SubWriterHolderWriter writer) {
super(writer);
}
/**
* Get the type parameters for the executable member.
*

49
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractMemberWriter.java
View File

@ -49,7 +49,6 @@ import jdk.javadoc.internal.doclets.formats.html.markup.Entity;
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.Links;
import jdk.javadoc.internal.doclets.toolkit.Resources;
import jdk.javadoc.internal.doclets.toolkit.util.DocFinder;
import jdk.javadoc.internal.doclets.toolkit.util.Utils;
@ -67,6 +66,8 @@ import static jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable.Kind.
/**
* The base class for member writers.
*
* Two primary methods are defined: {@link #buildSummary(Content)} and {@link #buildDetails(Content)}.
*/
public abstract class AbstractMemberWriter {
@ -76,7 +77,6 @@ public abstract class AbstractMemberWriter {
protected final SubWriterHolderWriter writer;
protected final Contents contents;
protected final Resources resources;
protected final Links links;
protected final HtmlIds htmlIds;
protected final TypeElement typeElement;
@ -123,14 +123,33 @@ public abstract class AbstractMemberWriter {
ANNOTATION_TYPE_MEMBER, METHODS
);
/**
* Creates a member writer for a given enclosing writer and kind of member.
*
* @param writer the enclosing "page" writer.
* @param kind the kind
*/
protected AbstractMemberWriter(ClassWriter writer, VisibleMemberTable.Kind kind) {
this(writer, writer.typeElement, kind);
}
/**
* Creates a member writer for a given enclosing writer.
* No type element or kind is provided, limiting the set of methods that can be used.
*
* @param writer the writer
*/
protected AbstractMemberWriter(SubWriterHolderWriter writer) {
this(writer, null, null);
}
/**
* Creates a member writer for a given enclosing writer, and optional type element and member kind.
* If no specific type element or kind is provided, methods that require such information
* may throw {@link NullPointerException}.
*
* @param writer the writer
*/
protected AbstractMemberWriter(SubWriterHolderWriter writer,
TypeElement typeElement,
VisibleMemberTable.Kind kind) {
@ -143,7 +162,6 @@ public abstract class AbstractMemberWriter {
this.utils = configuration.utils;
this.contents = configuration.getContents();
this.resources = configuration.docResources;
this.links = writer.links;
this.htmlIds = configuration.htmlIds;
visibleMemberTable = typeElement == null ? null : configuration.getVisibleMemberTable(typeElement);
@ -158,6 +176,26 @@ public abstract class AbstractMemberWriter {
*/
public abstract void buildDetails(Content target);
/**
* Builds the signature.
*
* @param target the content to which the documentation will be added
*/
protected abstract void buildSignature(Content target);
/**
* Builds the deprecation info.
*
* @param target the content to which the documentation will be added
*/
protected abstract void buildDeprecationInfo(Content target);
/**
* Builds the preview info.
*
* @param target the content to which the documentation will be added
*/
protected abstract void buildPreviewInfo(Content target);
/**
* Builds the "summary" for all members of this kind.
@ -179,7 +217,7 @@ public abstract class AbstractMemberWriter {
buildInheritedSummary(summaryTreeList);
if (!summaryTreeList.isEmpty()) {
Content member = getMemberSummaryHeader(typeElement, target);
Content member = getMemberSummaryHeader(target);
summaryTreeList.forEach(member::add);
buildSummary(target, member);
}
@ -271,12 +309,11 @@ public abstract class AbstractMemberWriter {
/**
* Returns the member summary header for the given class.
*
* @param typeElement the class the summary belongs to
* @param content the content to which the member summary will be added
*
* @return the member summary header
*/
public abstract Content getMemberSummaryHeader(TypeElement typeElement, Content content);
public abstract Content getMemberSummaryHeader(Content content);
/**
* Adds the given summary to the list of summaries.
*

32
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AbstractOverviewIndexWriter.java
View File

@ -35,7 +35,7 @@ import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
/**
* Abstract class to generate the overview files.
* Abstract class to generate the top-level "overview" files.
*/
public abstract class AbstractOverviewIndexWriter extends HtmlDocletWriter {
@ -46,10 +46,20 @@ public abstract class AbstractOverviewIndexWriter extends HtmlDocletWriter {
* @param filename Name of the module index file to be generated.
*/
public AbstractOverviewIndexWriter(HtmlConfiguration configuration,
DocPath filename) {
DocPath filename) {
super(configuration, filename);
}
/**
* {@return the page description, for the {@code <meta>} element}
*/
protected abstract String getDescription();
/**
* {@return the title for the page}
*/
protected abstract String getTitleKey();
/**
* Adds the overview summary comment for this documentation. Add one line
* summary at the top of the page and generate a link to the description,
@ -86,16 +96,10 @@ public abstract class AbstractOverviewIndexWriter extends HtmlDocletWriter {
}
}
/**
* Generate and prints the contents in the index file.
*
* @param title the title of the window
* @param description the content for the description META tag
* @throws DocFileIOException if there is a problem building the package index file
*/
protected void buildOverviewIndexFile(String title, String description)
throws DocFileIOException {
String windowOverview = resources.getText(title);
@Override
public void buildPage() throws DocFileIOException {
var titleKey = getTitleKey();
String windowOverview = resources.getText(titleKey);
Content body = getBody(getWindowTitle(windowOverview));
Content main = new ContentBuilder();
addOverviewHeader(main);
@ -105,8 +109,8 @@ public abstract class AbstractOverviewIndexWriter extends HtmlDocletWriter {
.addMainContent(main)
.setFooter(getFooter()));
printHtmlDocument(
configuration.metakeywords.getOverviewMetaKeywords(title, configuration.getOptions().docTitle()),
description, body);
configuration.metakeywords.getOverviewMetaKeywords(titleKey, configuration.getOptions().docTitle()),
getDescription(), body);
}
/**

32
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AllClassesIndexWriter.java
View File

@ -38,7 +38,6 @@ import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
import jdk.javadoc.internal.doclets.toolkit.util.IndexBuilder;
import jdk.javadoc.internal.doclets.toolkit.util.IndexItem;
@ -59,38 +58,15 @@ public class AllClassesIndexWriter extends HtmlDocletWriter {
* class.
*
* @param configuration The current configuration
* @param filename Path to the file which is getting generated.
* @param indexBuilder Unicode based Index from {@link IndexBuilder}
*/
public AllClassesIndexWriter(HtmlConfiguration configuration,
DocPath filename, IndexBuilder indexBuilder) {
super(configuration, filename);
public AllClassesIndexWriter(HtmlConfiguration configuration, IndexBuilder indexBuilder) {
super(configuration, DocPaths.ALLCLASSES_INDEX);
this.indexBuilder = indexBuilder;
}
/**
* Create AllClassesIndexWriter object.
*
* @param configuration The current configuration
* @param indexBuilder IndexBuilder object for all classes index.
* @throws DocFileIOException
*/
public static void generate(HtmlConfiguration configuration,
IndexBuilder indexBuilder) throws DocFileIOException {
generate(configuration, indexBuilder, DocPaths.ALLCLASSES_INDEX);
}
private static void generate(HtmlConfiguration configuration, IndexBuilder indexBuilder,
DocPath fileName) throws DocFileIOException {
AllClassesIndexWriter allClassGen = new AllClassesIndexWriter(configuration,
fileName, indexBuilder);
allClassGen.buildAllClassesFile();
}
/**
* Print all the classes in the file.
*/
protected void buildAllClassesFile() throws DocFileIOException {
@Override
public void buildPage() throws DocFileIOException {
String label = resources.getText("doclet.All_Classes_And_Interfaces");
Content allClassesContent = new ContentBuilder();
addContents(allClassesContent);

26
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AllPackagesIndexWriter.java
View File

@ -27,14 +27,13 @@ package jdk.javadoc.internal.doclets.formats.html;
import javax.lang.model.element.PackageElement;
import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
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.HtmlTree;
import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
import jdk.javadoc.internal.doclets.formats.html.markup.Text;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
/**
@ -46,31 +45,16 @@ public class AllPackagesIndexWriter extends HtmlDocletWriter {
* Construct AllPackagesIndexWriter object.
*
* @param configuration The current configuration
* @param filename Path to the file which is getting generated.
*/
public AllPackagesIndexWriter(HtmlConfiguration configuration, DocPath filename) {
super(configuration, filename);
}
/**
* Create AllPackagesIndexWriter object.
*
* @param configuration The current configuration
* @throws DocFileIOException
*/
public static void generate(HtmlConfiguration configuration) throws DocFileIOException {
generate(configuration, DocPaths.ALLPACKAGES_INDEX);
}
private static void generate(HtmlConfiguration configuration, DocPath fileName) throws DocFileIOException {
AllPackagesIndexWriter allPkgGen = new AllPackagesIndexWriter(configuration, fileName);
allPkgGen.buildAllPackagesFile();
public AllPackagesIndexWriter(HtmlConfiguration configuration) {
super(configuration, DocPaths.ALLPACKAGES_INDEX);
}
/**
* Print all the packages in the file.
*/
protected void buildAllPackagesFile() throws DocFileIOException {
@Override
public void buildPage() throws DocFileIOException {
String label = resources.getText("doclet.All_Packages");
Content mainContent = new ContentBuilder();
addPackages(mainContent);

35
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/AnnotationTypeMemberWriter.java
View File

@ -113,31 +113,19 @@ public class AnnotationTypeMemberWriter extends AbstractMemberWriter {
buildDefaultValueInfo(annotationContent);
}
/**
* Build the signature.
*
* @param target the content to which the documentation will be added
*/
@Override
protected void buildSignature(Content target) {
target.add(getSignature(currentMember));
}
/**
* Build the deprecation information.
*
* @param annotationContent the content to which the documentation will be added
*/
protected void buildDeprecationInfo(Content annotationContent) {
addDeprecated(currentMember, annotationContent);
@Override
protected void buildDeprecationInfo(Content target) {
addDeprecated(currentMember, target);
}
/**
* Build the preview information.
*
* @param annotationContent the content to which the documentation will be added
*/
protected void buildPreviewInfo(Content annotationContent) {
addPreview(currentMember, annotationContent);
@Override
protected void buildPreviewInfo(Content target) {
addPreview(currentMember, target);
}
/**
@ -171,8 +159,7 @@ public class AnnotationTypeMemberWriter extends AbstractMemberWriter {
}
@Override
public Content getMemberSummaryHeader(TypeElement typeElement,
Content content) {
public Content getMemberSummaryHeader(Content content) {
switch (kind) {
case ANNOTATION_TYPE_MEMBER_REQUIRED -> content.add(selectComment(
MarkerComments.START_OF_ANNOTATION_TYPE_REQUIRED_MEMBER_SUMMARY,
@ -187,10 +174,6 @@ public class AnnotationTypeMemberWriter extends AbstractMemberWriter {
return c;
}
protected Content getMemberHeader() {
return writer.getMemberHeader();
}
@Override
public void buildSummary(Content summariesList, Content content) {
writer.addSummary(HtmlStyle.memberSummary,
@ -338,7 +321,7 @@ public class AnnotationTypeMemberWriter extends AbstractMemberWriter {
: member.asType();
}
public void addDefaultValueInfo(Element member, Content annotationContent) {
protected void addDefaultValueInfo(Element member, Content annotationContent) {
if (utils.isAnnotationInterface(member.getEnclosingElement())) {
ExecutableElement ee = (ExecutableElement) member;
AnnotationValue value = ee.getDefaultValue();

55
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassUseWriter.java
View File

@ -43,6 +43,7 @@ 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.DocletException;
import jdk.javadoc.internal.doclets.toolkit.util.ClassTree;
import jdk.javadoc.internal.doclets.toolkit.util.ClassUseMapper;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
@ -86,14 +87,16 @@ public class ClassUseWriter extends SubWriterHolderWriter {
final NestedClassWriter classSubWriter;
/**
* Constructor.
* Creates a writer for a page listing the uses of a type element.
*
* @param filename the file to be generated.
* @param configuration the configuration
* @param mapper a "mapper" containing the usage information
* @param typeElement the type element
*/
public ClassUseWriter(HtmlConfiguration configuration,
ClassUseMapper mapper, DocPath filename,
ClassUseMapper mapper,
TypeElement typeElement) {
super(configuration, filename);
super(configuration, pathFor(configuration, typeElement));
this.typeElement = typeElement;
if (mapper.classToPackageAnnotations.containsKey(typeElement)) {
pkgToPackageAnnotations = new TreeSet<>(comparators.classUseComparator());
@ -138,15 +141,22 @@ public class ClassUseWriter extends SubWriterHolderWriter {
classSubWriter = new NestedClassWriter(this);
}
private static DocPath pathFor(HtmlConfiguration configuration, TypeElement typeElement) {
return configuration.docPaths.forPackage(typeElement)
.resolve(DocPaths.CLASS_USE)
.resolve(configuration.docPaths.forName( typeElement));
}
/**
* Write out class use pages.
* Write out class use and package use pages.
*
* @param configuration the configuration for this doclet
* @param classTree the class tree hierarchy
* @throws DocFileIOException if there is an error while generating the documentation
* @throws DocletException 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 DocletException {
var writerFactory = configuration.getWriterFactory();
var mapper = new ClassUseMapper(configuration, classTree);
boolean nodeprecated = configuration.getOptions().noDeprecated();
Utils utils = configuration.utils;
for (TypeElement aClass : configuration.getIncludedTypeElements()) {
@ -154,15 +164,16 @@ public class ClassUseWriter extends SubWriterHolderWriter {
// as deprecated, do not generate the class-use page. We will still generate
// the class-use page if the class is marked as deprecated but the containing
// package is not since it could still be linked from that package-use page.
if (!(nodeprecated &&
utils.isDeprecated(utils.containingPackage(aClass))))
ClassUseWriter.generate(configuration, mapper, aClass);
if (!(nodeprecated && utils.isDeprecated(utils.containingPackage(aClass)))) {
writerFactory.newClassUseWriter(aClass, mapper).buildPage();
}
}
for (PackageElement pkg : configuration.packages) {
// If -nodeprecated option is set and the package is marked
// as deprecated, do not generate the package-use page.
if (!(nodeprecated && utils.isDeprecated(pkg)))
PackageUseWriter.generate(configuration, mapper, pkg);
if (!(nodeprecated && utils.isDeprecated(pkg))) {
writerFactory.newPackageUseWriter(pkg, mapper).buildPage();
}
}
}
@ -180,27 +191,13 @@ public class ClassUseWriter extends SubWriterHolderWriter {
return map;
}
/**
* Generate a class page.
*
* @throws DocFileIOException if there is a problem while generating the documentation
*/
public static void generate(HtmlConfiguration configuration, ClassUseMapper mapper,
TypeElement typeElement) throws DocFileIOException {
ClassUseWriter clsgen;
DocPath path = configuration.docPaths.forPackage(typeElement)
.resolve(DocPaths.CLASS_USE)
.resolve(configuration.docPaths.forName( typeElement));
clsgen = new ClassUseWriter(configuration, mapper, path, typeElement);
clsgen.generateClassUseFile();
}
/**
* Generate the class use elements.
*
* @throws DocFileIOException if there is a problem while generating the documentation
*/
protected void generateClassUseFile() throws DocFileIOException {
@Override
public void buildPage() throws DocFileIOException {
HtmlTree body = getClassUseHeader();
Content mainContent = new ContentBuilder();
if (pkgSet.size() > 0) {

19
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ClassWriter.java
View File

@ -33,7 +33,6 @@ import java.util.SortedSet;
import java.util.TreeSet;
import java.util.stream.Collectors;
import javax.lang.model.element.AnnotationMirror;
import javax.lang.model.element.Element;
import javax.lang.model.element.ExecutableElement;
import javax.lang.model.element.ModuleElement;
@ -82,7 +81,6 @@ public class ClassWriter extends SubWriterHolderWriter {
"java.io.Serializable");
protected final TypeElement typeElement;
protected final VisibleMemberTable visibleMemberTable;
protected final ClassTree classTree;
protected final PropertyUtils.PropertyHelper pHelper;
@ -99,7 +97,6 @@ public class ClassWriter extends SubWriterHolderWriter {
configuration.currentTypeElement = typeElement;
this.classTree = classTree;
visibleMemberTable = configuration.getVisibleMemberTable(typeElement);
pHelper = new PropertyUtils.PropertyHelper(configuration, typeElement);
switch (typeElement.getKind()) {
@ -113,7 +110,8 @@ public class ClassWriter extends SubWriterHolderWriter {
return pHelper;
}
public void build() throws DocletException {
@Override
public void buildPage() throws DocletException {
buildClassDoc();
}
@ -697,7 +695,7 @@ public class ClassWriter extends SubWriterHolderWriter {
}
protected void addFunctionalInterfaceInfo (Content target) {
if (isFunctionalInterface()) {
if (utils.isFunctionalInterface(typeElement)) {
var dl = HtmlTree.DL(HtmlStyle.notes);
dl.add(HtmlTree.DT(contents.functionalInterface));
var dd = new HtmlTree(TagName.DD);
@ -707,17 +705,6 @@ public class ClassWriter extends SubWriterHolderWriter {
}
}
public boolean isFunctionalInterface() {
List<? extends AnnotationMirror> annotationMirrors = typeElement.getAnnotationMirrors();
for (AnnotationMirror anno : annotationMirrors) {
if (utils.isFunctionalInterface(anno)) {
return true;
}
}
return false;
}
protected void addClassDeprecationInfo(Content classInfo) {
List<? extends DeprecatedTree> deprs = utils.getDeprecatedTrees(typeElement);
if (utils.isDeprecated(typeElement)) {

11
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConstantsSummaryWriter.java
View File

@ -112,7 +112,8 @@ public class ConstantsSummaryWriter extends HtmlDocletWriter {
this.packageGroupHeadings = new TreeSet<>(utils::compareStrings);
}
public void build() throws DocletException {
@Override
public void buildPage() throws DocletException {
boolean anyConstants = configuration.packages.stream().anyMatch(this::hasConstantField);
if (!anyConstants) {
return;
@ -160,7 +161,7 @@ public class ConstantsSummaryWriter extends HtmlDocletWriter {
*/
protected void buildConstantSummaries() {
packageGroupHeadings.clear();
Content summaries = getConstantSummaries();
Content summaries = new ContentBuilder();
for (PackageElement aPackage : configuration.packages) {
if (hasConstantField(aPackage)) {
currentPackage = aPackage;
@ -359,12 +360,6 @@ public class ConstantsSummaryWriter extends HtmlDocletWriter {
bodyContents.addMainContent(section);
}
//@Override
// TODO: inline?
public Content getConstantSummaries() {
return new ContentBuilder();
}
void addPackageGroup(String abbrevPackageName, Content toContent) {
Content headingContent;
HtmlId anchorName;

41
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ConstructorWriter.java
View File

@ -56,9 +56,9 @@ public class ConstructorWriter extends AbstractExecutableMemberWriter {
private boolean foundNonPubConstructor = false;
/**
* Construct a new ConstructorWriterImpl.
* Construct a new member writer for constructors.
*
* @param writer The writer for the class that the constructors belong to.
* @param writer the writer for the class to which the constructors belong
*/
public ConstructorWriter(ClassWriter writer) {
super(writer, writer.typeElement, VisibleMemberTable.Kind.CONSTRUCTORS);
@ -120,31 +120,19 @@ public class ConstructorWriter extends AbstractExecutableMemberWriter {
}
}
/**
* Build the signature.
*
* @param constructorContent the content to which the documentation will be added
*/
protected void buildSignature(Content constructorContent) {
constructorContent.add(getSignature(currentConstructor));
@Override
protected void buildSignature(Content target) {
target.add(getSignature(currentConstructor));
}
/**
* Build the deprecation information.
*
* @param constructorContent the content to which the documentation will be added
*/
protected void buildDeprecationInfo(Content constructorContent) {
addDeprecated(currentConstructor, constructorContent);
@Override
protected void buildDeprecationInfo(Content target) {
addDeprecated(currentConstructor, target);
}
/**
* Build the preview information.
*
* @param constructorContent the content to which the documentation will be added
*/
protected void buildPreviewInfo(Content constructorContent) {
addPreview(currentConstructor, constructorContent);
@Override
protected void buildPreviewInfo(Content target) {
addPreview(currentConstructor, target);
}
/**
@ -169,8 +157,7 @@ public class ConstructorWriter extends AbstractExecutableMemberWriter {
}
@Override
public Content getMemberSummaryHeader(TypeElement typeElement,
Content content) {
public Content getMemberSummaryHeader(Content content) {
content.add(MarkerComments.START_OF_CONSTRUCTOR_SUMMARY);
Content c = new ContentBuilder();
writer.addSummaryHeader(this, c);
@ -297,8 +284,4 @@ public class ConstructorWriter extends AbstractExecutableMemberWriter {
content.add(code);
}
}
protected Content getMemberHeader(){
return writer.getMemberHeader();
}
}

45
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/DeprecatedListWriter.java
View File

@ -25,20 +25,19 @@
package jdk.javadoc.internal.doclets.formats.html;
import com.sun.source.doctree.DeprecatedTree;
import java.util.List;
import javax.lang.model.element.Element;
import com.sun.source.doctree.DeprecatedTree;
import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlAttr;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlId;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
import jdk.javadoc.internal.doclets.formats.html.markup.Text;
import jdk.javadoc.internal.doclets.toolkit.util.DeprecatedAPIListBuilder;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
/**
@ -53,27 +52,29 @@ public class DeprecatedListWriter extends SummaryListWriter<DeprecatedAPIListBui
* Constructor.
*
* @param configuration the configuration for this doclet
* @param filename the file to be generated
*/
public DeprecatedListWriter(HtmlConfiguration configuration, DocPath filename) {
super(configuration, filename, configuration.deprecatedAPIListBuilder);
public DeprecatedListWriter(HtmlConfiguration configuration) {
super(configuration, DocPaths.DEPRECATED_LIST, configuration.deprecatedAPIListBuilder);
}
/**
* Get list of all the deprecated classes and members in all the Packages
* specified on the command line.
* Then instantiate DeprecatedListWriter and generate File.
*
* @param configuration the current configuration of the doclet.
* @throws DocFileIOException if there is a problem writing the deprecated list
*/
public static void generate(HtmlConfiguration configuration) throws DocFileIOException {
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.DEPRECATED)) {
DocPath filename = DocPaths.DEPRECATED_LIST;
DeprecatedListWriter depr = new DeprecatedListWriter(configuration, filename);
depr.generateSummaryListFile(PageMode.DEPRECATED, "deprecated elements",
configuration.contents.deprecatedAPI, "doclet.Window_Deprecated_List");
}
@Override
protected PageMode getPageMode() {
return PageMode.DEPRECATED;
}
@Override
protected String getDescription() {
return "deprecated elements";
}
@Override
protected Content getHeadContent() {
return configuration.contents.deprecatedAPI;
}
@Override
protected String getTitleKey() {
return "doclet.Window_Deprecated_List";
}
@Override

223
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/DocFilesHandler.java
View File

@ -32,6 +32,7 @@ import com.sun.source.util.DocTreeFactory;
import jdk.javadoc.internal.doclets.formats.html.markup.BodyContents;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
import jdk.javadoc.internal.doclets.toolkit.DocFileElement;
import jdk.javadoc.internal.doclets.toolkit.DocletException;
import jdk.javadoc.internal.doclets.toolkit.util.DocFile;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
@ -42,7 +43,6 @@ import jdk.javadoc.internal.doclint.HtmlTag;
import javax.lang.model.element.Element;
import javax.lang.model.element.ModuleElement;
import javax.lang.model.element.PackageElement;
import javax.tools.FileObject;
import javax.tools.JavaFileManager.Location;
import java.net.URI;
@ -52,36 +52,45 @@ import java.util.List;
import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
/**
* A class to handle any files, including HTML files, found in the {@code doc-files}
* subdirectory for any given package.
*/
public class DocFilesHandler {
public final Element element;
public final Location location;
public final DocPath source;
public final HtmlConfiguration configuration;
private final Element element;
private final Location location;
private final DocPath source;
private final HtmlConfiguration configuration;
private final HtmlOptions options;
private final Utils utils;
private final WriterFactory writerFactory;
/**
* Constructor to construct the DocFilesWriter object.
* Constructor to construct the DocFilesHandler object.
*
* @param configuration the configuration of this doclet.
* @param element the containing element of the doc-files.
*
* @see WriterFactory#newDocFilesHandler(Element)
*/
public DocFilesHandler(HtmlConfiguration configuration, Element element) {
this.configuration = configuration;
this.options = configuration.getOptions();
this.utils = configuration.utils;
this.writerFactory = configuration.getWriterFactory();
this.element = element;
switch (element.getKind()) {
case MODULE -> {
ModuleElement mdle = (ModuleElement) element;
location = configuration.utils.getLocationForModule(mdle);
location = utils.getLocationForModule(mdle);
source = DocPaths.DOC_FILES;
}
case PACKAGE -> {
PackageElement pkg = (PackageElement) element;
location = configuration.utils.getLocationForPackage(pkg);
location = utils.getLocationForPackage(pkg);
// Note, given that we have a module-specific location,
// we want a module-relative path for the source, and not the
// standard path that may include the module directory
@ -97,10 +106,10 @@ public class DocFilesHandler {
* Copy doc-files directory and its contents from the source
* elements directory to the generated documentation directory.
*
* @throws DocFileIOException if there is a problem while copying
* @throws DocletException if there is a problem while copying
* the documentation files
*/
public void copyDocFiles() throws DocFileIOException {
public void copyDocFiles() throws DocletException {
boolean first = true;
for (DocFile srcdir : DocFile.list(configuration, location, source)) {
if (!srcdir.isDirectory()) {
@ -128,7 +137,7 @@ public class DocFilesHandler {
}
private void copyDirectory(DocFile srcdir, final DocPath dstDocPath,
boolean first) throws DocFileIOException {
boolean first) throws DocletException {
DocFile dstdir = DocFile.createFileForOutput(configuration, dstDocPath);
if (srcdir.isSameFile(dstdir)) {
return;
@ -177,117 +186,36 @@ public class DocFilesHandler {
}
}
private void handleHtmlFile(DocFile srcfile, DocPath dstPath) throws DocFileIOException {
Utils utils = configuration.utils;
FileObject fileObject = srcfile.getFileObject();
DocFileElement dfElement = new DocFileElement(utils, element, fileObject);
private void handleHtmlFile(DocFile srcFile, DocPath dstPath) throws DocletException {
var fileObject = srcFile.getFileObject();
var dfElement = new DocFileElement(utils, element, fileObject);
var path = dstPath.resolve(srcFile.getName());
DocPath dfilePath = dstPath.resolve(srcfile.getName());
PackageElement pkg = dfElement.getPackageElement();
HtmlDocletWriter docletWriter = new DocFileWriter(configuration, dfilePath, element, pkg);
List<? extends DocTree> localTags = getLocalHeaderTags(utils.getPreamble(dfElement));
Content localTagsContent = docletWriter.commentTagsToContent(dfElement, localTags, false);
String title = getWindowTitle(docletWriter, dfElement).trim();
HtmlTree htmlContent = docletWriter.getBody(title);
List<? extends DocTree> fullBody = utils.getFullBody(dfElement);
Content pageContent = docletWriter.commentTagsToContent(dfElement, fullBody, false);
docletWriter.addTagsInfo(dfElement, pageContent);
htmlContent.add(new BodyContents()
.setHeader(docletWriter.getHeader(PageMode.DOC_FILE, element))
.addMainContent(pageContent)
.setFooter(docletWriter.getFooter()));
docletWriter.printHtmlDocument(List.of(), null, localTagsContent, List.of(), htmlContent);
writerFactory.newDocFileWriter(path, dfElement).buildPage();
}
private List<? extends DocTree> getLocalHeaderTags(List<? extends DocTree> dtrees) {
List<DocTree> localTags = new ArrayList<>();
DocTreeFactory docTreeFactory = configuration.docEnv.getDocTrees().getDocTreeFactory();
boolean inHead = false;
boolean inTitle = false;
loop:
for (DocTree dt : dtrees) {
switch (dt.getKind()) {
case START_ELEMENT:
StartElementTree startElem = (StartElementTree)dt;
switch (HtmlTag.get(startElem.getName())) {
case HEAD:
inHead = true;
break;
case META:
break;
case TITLE:
inTitle = true;
break;
default:
if (inHead) {
localTags.add(startElem);
localTags.add(docTreeFactory.newTextTree("\n"));
}
}
break;
case END_ELEMENT:
EndElementTree endElem = (EndElementTree)dt;
switch (HtmlTag.get(endElem.getName())) {
case HEAD:
inHead = false;
break loop;
case TITLE:
inTitle = false;
break;
default:
if (inHead) {
localTags.add(endElem);
localTags.add(docTreeFactory.newTextTree("\n"));
}
}
break;
case ENTITY:
case TEXT:
if (inHead && !inTitle) {
localTags.add(dt);
}
break;
}
}
return localTags;
}
private String getWindowTitle(HtmlDocletWriter docletWriter, Element element) {
String t = configuration.utils.getHTMLTitle(element);
return docletWriter.getWindowTitle(t);
}
private static class DocFileWriter extends HtmlDocletWriter {
private final PackageElement pkg;
/**
* A writer to write out the processed form of an HTML file found in the {@code doc-files} subdirectory
* for a module or package.
*/
public static class DocFileWriter extends HtmlDocletWriter {
private final DocFileElement dfElement;
/**
* Constructor to construct the HtmlDocletWriter object.
* Constructor.
*
* @param configuration the configuration of this doclet
* @param path the file to be generated
* @param e the anchoring element
* @param pkg the package containing the doc file
* @param dfElement the element representing the doc file
*/
public DocFileWriter(HtmlConfiguration configuration, DocPath path, Element e, PackageElement pkg) {
public DocFileWriter(HtmlConfiguration configuration, DocPath path, DocFileElement dfElement) {
super(configuration, path);
switch (e.getKind()) {
case PACKAGE:
case MODULE:
break;
default:
throw new AssertionError("unsupported element: " + e.getKind());
}
this.pkg = pkg;
this.dfElement = dfElement;
}
@Override
protected Navigation getNavBar(PageMode pageMode, Element element) {
var pkg = dfElement.getPackageElement();
Content mdleLinkContent = getModuleLink(utils.elementUtils.getModuleOf(element),
contents.moduleLabel);
Content pkgLinkContent = getPackageLink(pkg, contents.packageLabel);
@ -295,5 +223,84 @@ public class DocFilesHandler {
.setNavLinkModule(mdleLinkContent)
.setNavLinkPackage(pkgLinkContent);
}
@Override
public void buildPage() throws DocFileIOException {
List<? extends DocTree> localTags = getLocalHeaderTags(utils.getPreamble(dfElement));
Content localTagsContent = commentTagsToContent(dfElement, localTags, false);
String title = getWindowTitle(this, dfElement).trim();
HtmlTree htmlContent = getBody(title);
List<? extends DocTree> fullBody = utils.getFullBody(dfElement);
Content pageContent = commentTagsToContent(dfElement, fullBody, false);
addTagsInfo(dfElement, pageContent);
htmlContent.add(new BodyContents()
.setHeader(getHeader(PageMode.DOC_FILE, dfElement.getElement()))
.addMainContent(pageContent)
.setFooter(getFooter()));
printHtmlDocument(List.of(), null, localTagsContent, List.of(), htmlContent);
}
private String getWindowTitle(HtmlDocletWriter docletWriter, Element element) {
String t = configuration.utils.getHTMLTitle(element);
return docletWriter.getWindowTitle(t);
}
private List<? extends DocTree> getLocalHeaderTags(List<? extends DocTree> dtrees) {
List<DocTree> localTags = new ArrayList<>();
DocTreeFactory docTreeFactory = configuration.docEnv.getDocTrees().getDocTreeFactory();
boolean inHead = false;
boolean inTitle = false;
loop:
for (DocTree dt : dtrees) {
switch (dt.getKind()) {
case START_ELEMENT:
StartElementTree startElem = (StartElementTree)dt;
switch (HtmlTag.get(startElem.getName())) {
case HEAD:
inHead = true;
break;
case META:
break;
case TITLE:
inTitle = true;
break;
default:
if (inHead) {
localTags.add(startElem);
localTags.add(docTreeFactory.newTextTree("\n"));
}
}
break;
case END_ELEMENT:
EndElementTree endElem = (EndElementTree)dt;
switch (HtmlTag.get(endElem.getName())) {
case HEAD:
inHead = false;
break loop;
case TITLE:
inTitle = false;
break;
default:
if (inHead) {
localTags.add(endElem);
localTags.add(docTreeFactory.newTextTree("\n"));
}
}
break;
case ENTITY:
case TEXT:
if (inHead && !inTitle) {
localTags.add(dt);
}
break;
}
}
return localTags;
}
}
}

37
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/EnumConstantWriter.java
View File

@ -67,14 +67,12 @@ public class EnumConstantWriter extends AbstractMemberWriter {
protected void buildEnumConstant(Content target) {
var enumConstants = getVisibleMembers(VisibleMemberTable.Kind.ENUM_CONSTANTS);
if (!enumConstants.isEmpty()) {
Content enumConstantsDetailsHeader = getEnumConstantsDetailsHeader(typeElement,
target);
Content enumConstantsDetailsHeader = getEnumConstantsDetailsHeader(target);
Content memberList = getMemberList();
for (Element enumConstant : enumConstants) {
currentElement = (VariableElement)enumConstant;
Content enumConstantContent = getEnumConstantsHeader(currentElement,
memberList);
Content enumConstantContent = getEnumConstantsHeader(currentElement);
buildSignature(enumConstantContent);
buildDeprecationInfo(enumConstantContent);
@ -90,29 +88,17 @@ public class EnumConstantWriter extends AbstractMemberWriter {
}
}
/**
* Build the signature.
*
* @param target the content to which the documentation will be added
*/
@Override
protected void buildSignature(Content target) {
target.add(getSignature(currentElement));
}
/**
* Build the deprecation information.
*
* @param target the content to which the documentation will be added
*/
@Override
protected void buildDeprecationInfo(Content target) {
addDeprecated(currentElement, target);
}
/**
* Build the preview information.
*
* @param target the content to which the documentation will be added
*/
@Override
protected void buildPreviewInfo(Content target) {
addPreview(currentElement, target);
}
@ -139,8 +125,7 @@ public class EnumConstantWriter extends AbstractMemberWriter {
}
@Override
public Content getMemberSummaryHeader(TypeElement typeElement,
Content content) {
public Content getMemberSummaryHeader(Content content) {
content.add(MarkerComments.START_OF_ENUM_CONSTANT_SUMMARY);
Content memberContent = new ContentBuilder();
writer.addSummaryHeader(this, memberContent);
@ -153,8 +138,7 @@ public class EnumConstantWriter extends AbstractMemberWriter {
HtmlIds.ENUM_CONSTANT_SUMMARY, summariesList, content);
}
protected Content getEnumConstantsDetailsHeader(TypeElement typeElement,
Content memberDetails) {
protected Content getEnumConstantsDetailsHeader(Content memberDetails) {
memberDetails.add(MarkerComments.START_OF_ENUM_CONSTANT_DETAILS);
var enumConstantsDetailsContent = new ContentBuilder();
var heading = HtmlTree.HEADING(Headings.TypeDeclaration.DETAILS_HEADING,
@ -163,8 +147,7 @@ public class EnumConstantWriter extends AbstractMemberWriter {
return enumConstantsDetailsContent;
}
protected Content getEnumConstantsHeader(VariableElement enumConstant,
Content enumConstantsDetails) {
protected Content getEnumConstantsHeader(VariableElement enumConstant) {
Content enumConstantsContent = new ContentBuilder();
var heading = HtmlTree.HEADING(Headings.TypeDeclaration.MEMBER_HEADING,
Text.of(name(enumConstant)));
@ -252,8 +235,4 @@ public class EnumConstantWriter extends AbstractMemberWriter {
String name = utils.getFullyQualifiedName(member) + "." + member.getSimpleName();
return writer.getDocLink(HtmlLinkInfo.Kind.SHOW_PREVIEW, member, name);
}
protected Content getMemberHeader(){
return writer.getMemberHeader();
}
}

36
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ExternalSpecsWriter.java
View File

@ -56,7 +56,6 @@ import jdk.javadoc.internal.doclets.formats.html.markup.Text;
import jdk.javadoc.internal.doclets.toolkit.DocletElement;
import jdk.javadoc.internal.doclets.toolkit.OverviewElement;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
import jdk.javadoc.internal.doclets.toolkit.util.IndexItem;
@ -68,8 +67,6 @@ import static java.util.stream.Collectors.toList;
*/
public class ExternalSpecsWriter extends HtmlDocletWriter {
private final Navigation navBar;
/**
* Cached contents of {@code <title>...</title>} tags of the HTML pages.
*/
@ -79,32 +76,25 @@ public class ExternalSpecsWriter extends HtmlDocletWriter {
* Constructs ExternalSpecsWriter object.
*
* @param configuration The current configuration
* @param filename Path to the file which is getting generated.
*/
public ExternalSpecsWriter(HtmlConfiguration configuration, DocPath filename) {
super(configuration, filename);
this.navBar = new Navigation(null, configuration, PageMode.EXTERNAL_SPECS, path);
}
public static void generate(HtmlConfiguration configuration) throws DocFileIOException {
generate(configuration, DocPaths.EXTERNAL_SPECS);
}
private static void generate(HtmlConfiguration configuration, DocPath fileName) throws DocFileIOException {
boolean hasExternalSpecs = configuration.mainIndex != null
&& !configuration.mainIndex.getItems(DocTree.Kind.SPEC).isEmpty();
if (!hasExternalSpecs) {
return;
}
ExternalSpecsWriter w = new ExternalSpecsWriter(configuration, fileName);
w.buildExternalSpecsPage();
configuration.conditionalPages.add(HtmlConfiguration.ConditionalPage.EXTERNAL_SPECS);
public ExternalSpecsWriter(HtmlConfiguration configuration) {
super(configuration, DocPaths.EXTERNAL_SPECS, false);
}
/**
* Prints all the "external specs" to the file.
*/
protected void buildExternalSpecsPage() throws DocFileIOException {
@Override
public void buildPage() throws DocFileIOException {
boolean hasExternalSpecs = configuration.mainIndex != null
&& !configuration.mainIndex.getItems(DocTree.Kind.SPEC).isEmpty();
if (!hasExternalSpecs) {
return;
}
writeGenerating();
configuration.conditionalPages.add(HtmlConfiguration.ConditionalPage.EXTERNAL_SPECS);
checkUniqueItems();
String title = resources.getText("doclet.External_Specifications");

38
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/FieldWriter.java
View File

@ -97,31 +97,19 @@ public class FieldWriter extends AbstractMemberWriter {
}
}
/**
* Build the signature.
*
* @param fieldContent the content to which the documentation will be added
*/
protected void buildSignature(Content fieldContent) {
fieldContent.add(getSignature(currentElement));
@Override
protected void buildSignature(Content target) {
target.add(getSignature(currentElement));
}
/**
* Build the deprecation information.
*
* @param fieldContent the content to which the documentation will be added
*/
protected void buildDeprecationInfo(Content fieldContent) {
addDeprecated(currentElement, fieldContent);
@Override
protected void buildDeprecationInfo(Content target) {
addDeprecated(currentElement, target);
}
/**
* Build the preview information.
*
* @param fieldContent the content to which the documentation will be added
*/
protected void buildPreviewInfo(Content fieldContent) {
addPreview(currentElement, fieldContent);
@Override
protected void buildPreviewInfo(Content target) {
addPreview(currentElement, target);
}
/**
@ -145,10 +133,8 @@ public class FieldWriter extends AbstractMemberWriter {
addTags(currentElement, fieldContent);
}
@Override
public Content getMemberSummaryHeader(TypeElement typeElement,
Content content) {
public Content getMemberSummaryHeader(Content content) {
content.add(MarkerComments.START_OF_FIELD_SUMMARY);
Content memberContent = new ContentBuilder();
writer.addSummaryHeader(this, memberContent);
@ -283,8 +269,4 @@ public class FieldWriter extends AbstractMemberWriter {
String name = utils.getFullyQualifiedName(member) + "." + member.getSimpleName();
return writer.getDocLink(HtmlLinkInfo.Kind.SHOW_PREVIEW, member, name);
}
protected Content getMemberHeader(){
return writer.getMemberHeader();
}
}

30
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HelpWriter.java
View File

@ -62,11 +62,9 @@ public class HelpWriter extends HtmlDocletWriter {
/**
* Constructor to construct HelpWriter object.
* @param configuration the configuration
* @param filename File to be generated.
*/
public HelpWriter(HtmlConfiguration configuration,
DocPath filename) {
super(configuration, filename);
public HelpWriter(HtmlConfiguration configuration) {
super(configuration, DocPaths.HELP_DOC);
// yes, INDEX is correct in the following line
overviewLink = links.createLink(DocPaths.INDEX, resources.getText("doclet.Overview"));
@ -78,27 +76,8 @@ public class HelpWriter extends HtmlDocletWriter {
indexLink = links.createLink(dp, resources.getText("doclet.Index"));
}
/**
* Construct the HelpWriter object and then use it to generate the help
* file. The name of the generated file is "help-doc.html". The help file
* will get generated if and only if "-helpfile" and "-nohelp" is not used
* on the command line.
*
* @param configuration the configuration
* @throws DocFileIOException if there is a problem while generating the documentation
*/
public static void generate(HtmlConfiguration configuration) throws DocFileIOException {
DocPath filename = DocPaths.HELP_DOC;
HelpWriter helpgen = new HelpWriter(configuration, filename);
helpgen.generateHelpFile();
}
/**
* Generate the help file contents.
*
* @throws DocFileIOException if there is a problem while generating the documentation
*/
protected void generateHelpFile() throws DocFileIOException {
@Override
public void buildPage() throws DocFileIOException {
String title = resources.getText("doclet.Window_Help_title");
HtmlTree body = getBody(getWindowTitle(title));
ContentBuilder helpFileContent = new ContentBuilder();
@ -208,7 +187,6 @@ public class HelpWriter extends HtmlDocletWriter {
return content;
}
/**
* Creates the page-specific help, adding an entry into the main table-of-contents.
*

62
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDoclet.java
View File

@ -32,6 +32,7 @@ import java.nio.file.InvalidPathException;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.EnumSet;
import java.util.HashMap;
import java.util.List;
import java.util.Locale;
@ -216,8 +217,8 @@ public class HtmlDoclet extends AbstractDoclet {
throws DocletException {
super.generateOtherFiles(classTree);
writerFactory.newConstantsSummaryWriter().build();
writerFactory.newSerializedFormWriter().build();
writerFactory.newConstantsSummaryWriter().buildPage();
writerFactory.newSerializedFormWriter().buildPage();
var options = configuration.getOptions();
if (options.linkSource()) {
@ -245,44 +246,49 @@ public class HtmlDoclet extends AbstractDoclet {
}
if (options.createTree()) {
TreeWriter.generate(configuration, classTree);
writerFactory.newTreeWriter(classTree).buildPage();
}
if (configuration.conditionalPages.contains((HtmlConfiguration.ConditionalPage.DEPRECATED))) {
DeprecatedListWriter.generate(configuration);
}
if (configuration.conditionalPages.contains((HtmlConfiguration.ConditionalPage.PREVIEW))) {
PreviewListWriter.generate(configuration);
}
if (configuration.conditionalPages.contains((HtmlConfiguration.ConditionalPage.NEW))) {
NewAPIListWriter.generate(configuration);
for (var cp : EnumSet.of(
HtmlConfiguration.ConditionalPage.DEPRECATED,
HtmlConfiguration.ConditionalPage.PREVIEW,
HtmlConfiguration.ConditionalPage.NEW)) {
if (configuration.conditionalPages.contains(cp)) {
var w = switch (cp) {
case DEPRECATED -> writerFactory.newDeprecatedListWriter();
case NEW -> writerFactory.newNewAPIListWriter();
case PREVIEW -> writerFactory.newPreviewListWriter();
default -> throw new AssertionError();
};
w.buildPage();
}
}
if (options.createOverview()) {
if (configuration.showModules) {
ModuleIndexWriter.generate(configuration);
} else {
PackageIndexWriter.generate(configuration);
}
var w = configuration.showModules
? writerFactory.newModuleIndexWriter()
: writerFactory.newPackageIndexWriter();
w.buildPage();
}
if (options.createIndex()) {
if (!options.noExternalSpecsPage()){
ExternalSpecsWriter.generate(configuration);
writerFactory.newExternalSpecsWriter().buildPage();
}
SystemPropertiesWriter.generate(configuration);
writerFactory.newSystemPropertiesWriter().buildPage();
configuration.mainIndex.addElements();
IndexBuilder allClassesIndex = new IndexBuilder(configuration, nodeprecated, true);
allClassesIndex.addElements();
AllClassesIndexWriter.generate(configuration, allClassesIndex);
writerFactory.newAllClassesIndexWriter(allClassesIndex).buildPage();
if (!configuration.packages.isEmpty()) {
AllPackagesIndexWriter.generate(configuration);
writerFactory.newAllPackagesIndexWriter().buildPage();
}
configuration.mainIndex.createSearchIndexFiles();
IndexWriter.generate(configuration);
SearchWriter.generate(configuration);
writerFactory.newSearchWriter().buildPage();
}
if (options.createOverview()) {
@ -292,8 +298,10 @@ public class HtmlDoclet extends AbstractDoclet {
}
if (options.helpFile().isEmpty() && !options.noHelp()) {
HelpWriter.generate(configuration);
var w = writerFactory.newHelpWriter();
w.buildPage();
}
// If a stylesheet file is not specified, copy the default stylesheet
// and replace newline with platform-specific newline.
DocFile f;
@ -399,7 +407,7 @@ public class HtmlDoclet extends AbstractDoclet {
!(configuration.isGeneratedDoc(te) && utils.isIncluded(te))) {
continue;
}
writerFactory.newClassWriter(te, classTree).build();
writerFactory.newClassWriter(te, classTree).buildPage();
}
}
@ -408,7 +416,7 @@ public class HtmlDoclet extends AbstractDoclet {
if (configuration.showModules) {
List<ModuleElement> mdles = new ArrayList<>(configuration.modulePackages.keySet());
for (ModuleElement mdle : mdles) {
writerFactory.newModuleWriter(mdle).build();
writerFactory.newModuleWriter(mdle).buildPage();
}
}
}
@ -423,7 +431,7 @@ public class HtmlDoclet extends AbstractDoclet {
// deprecated, do not generate the package-summary.html, package-frame.html
// and package-tree.html pages for that package.
if (!(options.noDeprecated() && utils.isDeprecated(pkg))) {
writerFactory.newPackageWriter(pkg).build();
writerFactory.newPackageWriter(pkg).buildPage();
if (options.createTree()) {
PackageTreeWriter.generate(configuration, pkg, options.noDeprecated());
}

24
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
View File

@ -94,6 +94,7 @@ import jdk.javadoc.internal.doclets.formats.html.markup.Text;
import jdk.javadoc.internal.doclets.formats.html.markup.TextBuilder;
import jdk.javadoc.internal.doclets.formats.html.taglets.Taglet;
import jdk.javadoc.internal.doclets.formats.html.taglets.TagletWriter;
import jdk.javadoc.internal.doclets.toolkit.DocletException;
import jdk.javadoc.internal.doclets.toolkit.Messages;
import jdk.javadoc.internal.doclets.toolkit.Resources;
import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
@ -115,11 +116,10 @@ import static com.sun.source.doctree.DocTree.Kind.TEXT;
/**
* Class for the Html Format Code Generation specific to JavaDoc.
* This Class contains methods related to the Html Code Generation which
* are used extensively while generating the entire documentation.
* The base class for classes that write complete HTML pages to be included in the overall API documentation.
* The primary method is {@link #buildPage()}.
*/
public class HtmlDocletWriter {
public abstract class HtmlDocletWriter {
/**
* Relative path from the file getting generated to the destination
@ -137,12 +137,6 @@ public class HtmlDocletWriter {
*/
public final DocPath path;
/**
* Name of the file getting generated. If the file getting generated is
* "java/lang/Object.html", then the filename is "Object.html".
*/
public final DocPath filename;
/**
* The global configuration information for this run.
*/
@ -209,7 +203,7 @@ public class HtmlDocletWriter {
* @param path the file to be generated.
* @param generating whether to write a "Geneterating ..." message to the console
*/
public HtmlDocletWriter(HtmlConfiguration configuration, DocPath path, boolean generating) {
protected HtmlDocletWriter(HtmlConfiguration configuration, DocPath path, boolean generating) {
this.configuration = configuration;
this.options = configuration.getOptions();
this.contents = configuration.getContents();
@ -221,7 +215,6 @@ public class HtmlDocletWriter {
this.htmlIds = configuration.htmlIds;
this.path = path;
this.pathToRoot = path.parent().invert();
this.filename = path.basename();
this.docPaths = configuration.docPaths;
this.mainBodyScript = new Script();
@ -230,6 +223,13 @@ public class HtmlDocletWriter {
}
}
/**
* The top-level method to generate and write the page represented by this writer.
*
* @throws DocletException if a problem occurs while building or writing the page
*/
public abstract void buildPage() throws DocletException;
/**
* Writes a "Generating _file_" message to the console
*/

14
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIds.java
View File

@ -106,8 +106,6 @@ public class HtmlIds {
static final HtmlId SERVICES = HtmlId.of("services-summary");
static final HtmlId SKIP_NAVBAR_TOP = HtmlId.of("skip-navbar-top");
static final HtmlId UNNAMED_PACKAGE_ANCHOR = HtmlId.of("unnamed-package");
private static final String ENUM_CONSTANTS_INHERITANCE = "enum-constants-inherited-from-class-";
private static final String FIELDS_INHERITANCE = "fields-inherited-from-class-";
private static final String METHODS_INHERITANCE = "methods-inherited-from-class-";
private static final String NESTED_CLASSES_INHERITANCE = "nested-classes-inherited-from-class-";
@ -323,17 +321,6 @@ public class HtmlIds {
return forInherited(FIELDS_INHERITANCE, element);
}
/**
* Returns an id for the list of enum constants inherited from a class or interface.
*
* @param element the class or interface
*
* @return the id
*/
HtmlId forInheritedEnumConstants(TypeElement element) {
return forInherited(ENUM_CONSTANTS_INHERITANCE, element);
}
/**
* Returns an id for the list of methods inherited from a class or interface.
*
@ -487,7 +474,6 @@ public class HtmlIds {
return HtmlId.of(tableId.name() + ".tabpanel");
}
/**
* Returns an id for the "preview" section for an element.
*

2
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlIndexBuilder.java
View File

@ -83,7 +83,6 @@ public class HtmlIndexBuilder extends IndexBuilder {
return;
}
Map<String,Integer> duplicateLabelCheck = new HashMap<>();
for (Character ch : getFirstCharacters()) {
for (IndexItem item : getItems(ch)) {
@ -149,7 +148,6 @@ public class HtmlIndexBuilder extends IndexBuilder {
}
}
/**
* Generates the set of index files used by interactive search.
*

13
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/IndexRedirectWriter.java
View File

@ -57,22 +57,19 @@ public class IndexRedirectWriter extends HtmlDocletWriter {
public static void generate(HtmlConfiguration configuration, DocPath fileName, DocPath target)
throws DocFileIOException {
IndexRedirectWriter indexRedirect = new IndexRedirectWriter(configuration, fileName, target);
indexRedirect.generateIndexFile();
var indexRedirect = new IndexRedirectWriter(configuration, fileName, target);
indexRedirect.buildPage();
}
private DocPath target;
private final DocPath target;
private IndexRedirectWriter(HtmlConfiguration configuration, DocPath filename, DocPath target) {
super(configuration, filename);
this.target = target;
}
/**
* Generate an index file that redirects to an alternate file.
* @throws DocFileIOException if there is a problem generating the file
*/
private void generateIndexFile() throws DocFileIOException {
@Override
public void buildPage() throws DocFileIOException {
Head head = new Head(path, configuration.getDocletVersion(), configuration.getBuildDate())
.setTimestamp(!options.noTimestamp())
.setDescription("index redirect")

55
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/IndexWriter.java
View File

@ -46,6 +46,7 @@ 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.formats.html.markup.Text;
import jdk.javadoc.internal.doclets.toolkit.DocletException;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
@ -63,6 +64,8 @@ public class IndexWriter extends HtmlDocletWriter {
protected final IndexBuilder mainIndex;
protected final boolean splitIndex;
protected final List<Character> allFirstCharacters;
protected final List<Character> displayFirstCharacters;
/**
* Generates the main index of all documented elements, terms defined in some documentation
@ -72,9 +75,10 @@ public class IndexWriter extends HtmlDocletWriter {
* initial letter; otherwise, a single page is generated for all items in the index.
*
* @param configuration the configuration
* @throws DocFileIOException if an error occurs while writing the files
* @throws DocletException if an error occurs while writing the files
*/
public static void generate(HtmlConfiguration configuration) throws DocFileIOException {
public static void generate(HtmlConfiguration configuration) throws DocletException {
var writerFactory = configuration.getWriterFactory();
IndexBuilder mainIndex = configuration.mainIndex;
List<Character> firstCharacters = mainIndex.getFirstCharacters();
if (configuration.getOptions().splitIndex()) {
@ -82,12 +86,10 @@ public class IndexWriter extends HtmlDocletWriter {
while (iter.hasNext()) {
Character ch = iter.next();
DocPath file = DocPaths.INDEX_FILES.resolve(DocPaths.indexN(iter.nextIndex()));
IndexWriter writer = new IndexWriter(configuration, file);
writer.generateIndexFile(firstCharacters, List.of(ch));
writerFactory.newIndexWriter(file, firstCharacters, List.of(ch)).buildPage();
}
} else {
IndexWriter writer = new IndexWriter(configuration, DocPaths.INDEX_ALL);
writer.generateIndexFile(firstCharacters, firstCharacters);
writerFactory.newIndexWriter(DocPaths.INDEX_ALL, firstCharacters, firstCharacters).buildPage();
}
}
@ -96,22 +98,25 @@ public class IndexWriter extends HtmlDocletWriter {
*
* @param configuration the current configuration
* @param path the file to be generated
* @param allFirstCharacters the initial characters of all index items
* @param displayFirstCharacters the initial characters of the index items to appear on this page
*/
protected IndexWriter(HtmlConfiguration configuration, DocPath path) {
protected IndexWriter(HtmlConfiguration configuration, DocPath path,
List<Character> allFirstCharacters, List<Character> displayFirstCharacters) {
super(configuration, path);
this.mainIndex = configuration.mainIndex;
this.splitIndex = configuration.getOptions().splitIndex();
this.allFirstCharacters = allFirstCharacters;
this.displayFirstCharacters = displayFirstCharacters;
}
/**
* Generates a page containing some or all of the overall index.
*
* @param allFirstCharacters the initial characters of all index items
* @param displayFirstCharacters the initial characters of the index items to appear on this page
* @throws DocFileIOException if an error occurs while writing the page
*/
protected void generateIndexFile(List<Character> allFirstCharacters,
List<Character> displayFirstCharacters) throws DocFileIOException {
@Override
public void buildPage() throws DocFileIOException {
String title = splitIndex
? resources.getText("doclet.Window_Split_Index", displayFirstCharacters.get(0))
: resources.getText("doclet.Window_Single_Index");
@ -189,43 +194,35 @@ public class IndexWriter extends HtmlDocletWriter {
Element element = item.getElement();
String label = item.getLabel();
switch (element.getKind()) {
case MODULE:
case MODULE -> {
dt = HtmlTree.DT(getModuleLink((ModuleElement) element, Text.of(label)));
dt.add(" - ").add(contents.module_).add(" " + label);
break;
}
case PACKAGE:
case PACKAGE -> {
dt = HtmlTree.DT(getPackageLink((PackageElement) element, Text.of(label)));
if (configuration.showModules) {
item.setContainingModule(utils.getFullyQualifiedName(utils.containingModule(element)));
}
dt.add(" - ").add(contents.package_).add(" " + label);
break;
}
case CLASS:
case ENUM:
case RECORD:
case ANNOTATION_TYPE:
case INTERFACE:
case CLASS, ENUM, RECORD, ANNOTATION_TYPE, INTERFACE -> {
dt = HtmlTree.DT(getLink(new HtmlLinkInfo(configuration,
HtmlLinkInfo.Kind.SHOW_TYPE_PARAMS_IN_LABEL, (TypeElement) element).style(HtmlStyle.typeNameLink)));
dt.add(" - ");
addClassInfo((TypeElement) element, dt);
break;
}
case CONSTRUCTOR:
case METHOD:
case FIELD:
case ENUM_CONSTANT:
case CONSTRUCTOR, METHOD, FIELD, ENUM_CONSTANT -> {
TypeElement containingType = item.getContainingTypeElement();
dt = HtmlTree.DT(getDocLink(HtmlLinkInfo.Kind.PLAIN, containingType, element,
label, HtmlStyle.memberNameLink));
label, HtmlStyle.memberNameLink));
dt.add(" - ");
addMemberDesc(element, containingType, dt);
break;
}
default:
throw new Error();
default -> throw new Error();
}
target.add(dt);
var dd = new HtmlTree(TagName.DD);

36
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/MethodWriter.java
View File

@ -119,31 +119,19 @@ public class MethodWriter extends AbstractExecutableMemberWriter {
}
}
/**
* Build the signature.
*
* @param methodContent the content to which the documentation will be added
*/
protected void buildSignature(Content methodContent) {
methodContent.add(getSignature(currentMethod));
@Override
protected void buildSignature(Content target) {
target.add(getSignature(currentMethod));
}
/**
* Build the deprecation information.
*
* @param methodContent the content to which the documentation will be added
*/
protected void buildDeprecationInfo(Content methodContent) {
addDeprecated(currentMethod, methodContent);
@Override
protected void buildDeprecationInfo(Content target) {
addDeprecated(currentMethod, target);
}
/**
* Build the preview information.
*
* @param methodContent the content to which the documentation will be added
*/
protected void buildPreviewInfo(Content methodContent) {
addPreview(currentMethod, methodContent);
@Override
protected void buildPreviewInfo(Content target) {
addPreview(currentMethod, target);
}
/**
@ -174,7 +162,7 @@ public class MethodWriter extends AbstractExecutableMemberWriter {
}
@Override
public Content getMemberSummaryHeader(TypeElement typeElement, Content target) {
public Content getMemberSummaryHeader(Content target) {
target.add(MarkerComments.START_OF_METHOD_SUMMARY);
Content memberContent = new ContentBuilder();
writer.addSummaryHeader(this, memberContent);
@ -434,8 +422,4 @@ public class MethodWriter extends AbstractExecutableMemberWriter {
}
return new ContentBuilder();
}
protected Content getMemberHeader(){
return writer.getMemberHeader();
}
}

25
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleIndexWriter.java
View File

@ -34,8 +34,6 @@ import javax.lang.model.element.ModuleElement;
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.Text;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
/**
@ -52,23 +50,20 @@ public class ModuleIndexWriter extends AbstractOverviewIndexWriter {
* Construct the ModuleIndexWriter.
*
* @param configuration the configuration object
* @param filename the name of the generated file
*/
public ModuleIndexWriter(HtmlConfiguration configuration, DocPath filename) {
super(configuration, filename);
public ModuleIndexWriter(HtmlConfiguration configuration) {
super(configuration, DocPaths.INDEX);
modules = configuration.modules;
}
/**
* Generate the module index page.
*
* @param configuration the current configuration of the doclet.
* @throws DocFileIOException if there is a problem generating the module index page
*/
public static void generate(HtmlConfiguration configuration) throws DocFileIOException {
DocPath filename = DocPaths.INDEX;
ModuleIndexWriter mdlgen = new ModuleIndexWriter(configuration, filename);
mdlgen.buildOverviewIndexFile("doclet.Window_Overview_Summary", "module index");
@Override
public String getDescription() {
return "module index";
}
@Override
public String getTitleKey() {
return "doclet.Window_Overview_Summary";
}
/**

9
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/ModuleWriter.java
View File

@ -165,12 +165,8 @@ public class ModuleWriter extends HtmlDocletWriter {
computeModulesData();
}
/**
* Build the module summary.
*
* @throws DocletException if there is a problem while building the documentation
*/
public void build() throws DocletException {
@Override
public void buildPage() throws DocletException {
buildModuleDoc();
}
@ -681,6 +677,7 @@ public class ModuleWriter extends HtmlDocletWriter {
row.add(getPackageExportOpensTo(entry.openedTo));
}
Content summary = new ContentBuilder();
// TODO: consider deprecation info, addPackageDeprecationInfo
addPreviewSummary(pkg, summary);
addSummaryComment(pkg, summary);
row.add(summary);

7
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/NestedClassWriter.java
View File

@ -57,9 +57,12 @@ public class NestedClassWriter extends AbstractMemberWriter {
throw new UnsupportedOperationException();
}
protected void buildSignature(Content target) { }
protected void buildDeprecationInfo(Content target) { }
protected void buildPreviewInfo(Content target) { }
@Override
public Content getMemberSummaryHeader(TypeElement typeElement,
Content content) {
public Content getMemberSummaryHeader(Content content) {
content.add(MarkerComments.START_OF_NESTED_CLASS_SUMMARY);
Content memberContent = new ContentBuilder();
writer.addSummaryHeader(this, memberContent);

42
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/NewAPIListWriter.java
View File

@ -25,9 +25,12 @@
package jdk.javadoc.internal.doclets.formats.html;
import java.util.List;
import javax.lang.model.element.Element;
import com.sun.source.doctree.DocTree;
import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlAttr;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlId;
@ -35,13 +38,9 @@ import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
import jdk.javadoc.internal.doclets.formats.html.markup.Text;
import jdk.javadoc.internal.doclets.toolkit.util.CommentHelper;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
import jdk.javadoc.internal.doclets.toolkit.util.NewAPIBuilder;
import java.util.List;
import static com.sun.source.doctree.DocTree.Kind.SINCE;
/**
@ -54,23 +53,28 @@ public class NewAPIListWriter extends SummaryListWriter<NewAPIBuilder> {
*
* @param configuration the configuration for this doclet
*/
public NewAPIListWriter(HtmlConfiguration configuration, DocPath filename) {
super(configuration, filename, configuration.newAPIPageBuilder);
public NewAPIListWriter(HtmlConfiguration configuration) {
super(configuration, DocPaths.NEW_LIST, configuration.newAPIPageBuilder);
}
/**
* If the "New API" page is configured this method instantiates a NewAPIListWriter
* and generates the file.
*
* @param configuration the current configuration of the doclet.
* @throws DocFileIOException if there is a problem writing the new API list
*/
public static void generate(HtmlConfiguration configuration) throws DocFileIOException {
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.NEW)) {
NewAPIListWriter writer = new NewAPIListWriter(configuration, DocPaths.NEW_LIST);
writer.generateSummaryListFile(PageMode.NEW, "new elements",
Text.of(getHeading(configuration)), "doclet.Window_New_List");
}
@Override
protected PageMode getPageMode() {
return PageMode.NEW;
}
@Override
protected String getDescription() {
return "new elements";
}
@Override
protected Content getHeadContent() {
return Text.of(getHeading(configuration));
}
@Override
protected String getTitleKey() {
return "doclet.Window_New_List";
}
@Override

31
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageIndexWriter.java
View File

@ -25,15 +25,15 @@
package jdk.javadoc.internal.doclets.formats.html;
import java.util.*;
import java.util.Map;
import java.util.Set;
import java.util.SortedSet;
import javax.lang.model.element.PackageElement;
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.Text;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
import jdk.javadoc.internal.doclets.toolkit.util.Group;
@ -43,7 +43,7 @@ import jdk.javadoc.internal.doclets.toolkit.util.Group;
public class PackageIndexWriter extends AbstractOverviewIndexWriter {
/**
* A Set of Packages to be documented.
* The Set of Packages to be documented.
*/
protected SortedSet<PackageElement> packages;
@ -53,24 +53,21 @@ public class PackageIndexWriter extends AbstractOverviewIndexWriter {
* the order of groups specified by the user.
*
* @param configuration the configuration for this doclet
* @param filename the path of the page to be generated
* @see Group
*/
public PackageIndexWriter(HtmlConfiguration configuration, DocPath filename) {
super(configuration, filename);
public PackageIndexWriter(HtmlConfiguration configuration) {
super(configuration, DocPaths.INDEX);
packages = configuration.packages;
}
/**
* Generate the package index page.
*
* @param configuration the current configuration of the doclet.
* @throws DocFileIOException if there is a problem generating the package index page
*/
public static void generate(HtmlConfiguration configuration) throws DocFileIOException {
DocPath filename = DocPaths.INDEX;
PackageIndexWriter packgen = new PackageIndexWriter(configuration, filename);
packgen.buildOverviewIndexFile("doclet.Window_Overview_Summary", "package index");
@Override
public String getDescription() {
return "package index";
}
@Override
public String getTitleKey() {
return "doclet.Window_Overview_Summary";
}
/**

21
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageTreeWriter.java
View File

@ -28,14 +28,13 @@ package jdk.javadoc.internal.doclets.formats.html;
import javax.lang.model.element.Element;
import javax.lang.model.element.PackageElement;
import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
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.HtmlTree;
import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
import jdk.javadoc.internal.doclets.toolkit.util.ClassTree;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
@ -55,12 +54,12 @@ public class PackageTreeWriter extends AbstractTreeWriter {
/**
* Constructor.
* @param configuration the configuration
* @param path the docpath to generate files into
* @param packageElement the current package
*/
public PackageTreeWriter(HtmlConfiguration configuration, DocPath path, PackageElement packageElement) {
super(configuration, path,
new ClassTree(configuration.typeElementCatalog.allClasses(packageElement), configuration));
public PackageTreeWriter(HtmlConfiguration configuration, PackageElement packageElement) {
super(configuration,
configuration.docPaths.forPackage(packageElement).resolve(DocPaths.PACKAGE_TREE),
new ClassTree(configuration.typeElementCatalog.allClasses(packageElement), configuration));
this.packageElement = packageElement;
}
@ -77,9 +76,10 @@ public class PackageTreeWriter extends AbstractTreeWriter {
public static void generate(HtmlConfiguration configuration,
PackageElement pkg, boolean noDeprecated)
throws DocFileIOException {
DocPath path = configuration.docPaths.forPackage(pkg).resolve(DocPaths.PACKAGE_TREE);
PackageTreeWriter packgen = new PackageTreeWriter(configuration, path, pkg);
packgen.generatePackageTreeFile();
if (!(noDeprecated && configuration.utils.isDeprecated(pkg))) {
var packgen = new PackageTreeWriter(configuration, pkg);
packgen.buildPage();
}
}
/**
@ -87,7 +87,8 @@ public class PackageTreeWriter extends AbstractTreeWriter {
*
* @throws DocFileIOException if there is a problem generating the package tree file
*/
protected void generatePackageTreeFile() throws DocFileIOException {
@Override
public void buildPage() throws DocFileIOException {
HtmlTree body = getPackageTreeHeader();
Content mainContent = new ContentBuilder();
Content headContent = packageElement.isUnnamed()

24
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageUseWriter.java
View File

@ -59,13 +59,12 @@ public class PackageUseWriter extends SubWriterHolderWriter {
*
* @param configuration the configuration
* @param mapper a mapper to provide details of where elements are used
* @param filename the file to be generated
* @param pkgElement the package element to be documented
*/
public PackageUseWriter(HtmlConfiguration configuration,
ClassUseMapper mapper, DocPath filename,
ClassUseMapper mapper,
PackageElement pkgElement) {
super(configuration, configuration.docPaths.forPackage(pkgElement).resolve(filename));
super(configuration, pathFor(configuration, pkgElement));
this.packageElement = pkgElement;
// by examining all classes in this package, find what packages
@ -89,27 +88,16 @@ public class PackageUseWriter extends SubWriterHolderWriter {
}
}
/**
* Generate a class page.
*
* @param configuration the current configuration of the doclet.
* @param mapper the mapping of the class usage.
* @param pkgElement the package being documented.
* @throws DocFileIOException if there is a problem generating the package use page
*/
public static void generate(HtmlConfiguration configuration,
ClassUseMapper mapper, PackageElement pkgElement)
throws DocFileIOException {
DocPath filename = DocPaths.PACKAGE_USE;
PackageUseWriter pkgusegen = new PackageUseWriter(configuration, mapper, filename, pkgElement);
pkgusegen.generatePackageUseFile();
private static DocPath pathFor(HtmlConfiguration configuration, PackageElement packageElement) {
return configuration.docPaths.forPackage(packageElement).resolve(DocPaths.PACKAGE_USE);
}
/**
* Generate the package use list.
* @throws DocFileIOException if there is a problem generating the package use page
*/
protected void generatePackageUseFile() throws DocFileIOException {
@Override
public void buildPage() throws DocFileIOException {
HtmlTree body = getBody();
Content mainContent = new ContentBuilder();
if (usingPackageToUsedClasses.isEmpty()) {

12
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PackageWriter.java
View File

@ -100,12 +100,8 @@ public class PackageWriter extends HtmlDocletWriter {
computePackageData();
}
/**
* Build the package summary.
*
* @throws DocletException if there is a problem while building the documentation
*/
public void build() throws DocletException {
@Override
public void buildPage() throws DocletException {
buildPackageDoc();
}
@ -174,7 +170,6 @@ public class PackageWriter extends HtmlDocletWriter {
addAllClassesAndInterfacesSummary(summariesList);
}
/**
* Build the description of the summary.
*
@ -328,7 +323,6 @@ public class PackageWriter extends HtmlDocletWriter {
summaryContent, showModules);
}
/**
* Add all types to the content.
*
@ -369,7 +363,7 @@ public class PackageWriter extends HtmlDocletWriter {
}
}
public void addPackageSummary(List<PackageElement> packages, Content label,
protected void addPackageSummary(List<PackageElement> packages, Content label,
TableHeader tableHeader, Content summaryContent,
boolean showModules) {
if (!packages.isEmpty()) {

39
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PreviewListWriter.java
View File

@ -38,8 +38,6 @@ import jdk.javadoc.internal.doclets.formats.html.markup.HtmlId;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
import jdk.javadoc.internal.doclets.formats.html.markup.Text;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
import jdk.javadoc.internal.doclets.toolkit.util.PreviewAPIListBuilder;
@ -53,26 +51,29 @@ public class PreviewListWriter extends SummaryListWriter<PreviewAPIListBuilder>
* Constructor.
*
* @param configuration the configuration for this doclet
* @param filename the file to be generated
*/
public PreviewListWriter(HtmlConfiguration configuration, DocPath filename) {
super(configuration, filename, configuration.previewAPIListBuilder);
public PreviewListWriter(HtmlConfiguration configuration) {
super(configuration, DocPaths.PREVIEW_LIST, configuration.previewAPIListBuilder);
}
/**
* Get list of all the preview elements.
* Then instantiate PreviewListWriter and generate File.
*
* @param configuration the current configuration of the doclet.
* @throws DocFileIOException if there is a problem writing the preview list
*/
public static void generate(HtmlConfiguration configuration) throws DocFileIOException {
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.PREVIEW)) {
DocPath filename = DocPaths.PREVIEW_LIST;
PreviewListWriter depr = new PreviewListWriter(configuration, filename);
depr.generateSummaryListFile(PageMode.PREVIEW, "preview elements",
configuration.contents.previewAPI, "doclet.Window_Preview_List");
}
@Override
protected PageMode getPageMode() {
return PageMode.PREVIEW;
}
@Override
protected String getDescription() {
return "preview elements";
}
@Override
protected Content getHeadContent() {
return configuration.contents.previewAPI;
}
@Override
protected String getTitleKey() {
return "doclet.Window_Preview_List";
}
@Override

35
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/PropertyWriter.java
View File

@ -80,6 +80,8 @@ public class PropertyWriter extends AbstractMemberWriter {
Content propertyContent = getPropertyHeaderContent(currentProperty);
buildSignature(propertyContent);
buildDeprecationInfo(propertyContent);
buildPreviewInfo(propertyContent);
buildPropertyComments(propertyContent);
buildTagInfo(propertyContent);
@ -90,31 +92,19 @@ public class PropertyWriter extends AbstractMemberWriter {
}
}
/**
* Build the signature.
*
* @param propertyContent the content to which the documentation will be added
*/
protected void buildSignature(Content propertyContent) {
propertyContent.add(getSignature(currentProperty));
@Override
protected void buildSignature(Content target) {
target.add(getSignature(currentProperty));
}
/**
* Build the deprecation information.
*
* @param propertyContent the content to which the documentation will be added
*/
protected void buildDeprecationInfo(Content propertyContent) {
addDeprecated(currentProperty, propertyContent);
@Override
protected void buildDeprecationInfo(Content target) {
addDeprecated(currentProperty, target);
}
/**
* Build the preview information.
*
* @param propertyContent the content to which the documentation will be added
*/
protected void buildPreviewInfo(Content propertyContent) {
addPreview(currentProperty, propertyContent);
@Override
protected void buildPreviewInfo(Content target) {
addPreview(currentProperty, target);
}
/**
@ -156,9 +146,8 @@ public class PropertyWriter extends AbstractMemberWriter {
}
}
@Override
public Content getMemberSummaryHeader(TypeElement typeElement, Content content) {
public Content getMemberSummaryHeader(Content content) {
content.add(MarkerComments.START_OF_PROPERTY_SUMMARY);
Content memberContent = new ContentBuilder();
writer.addSummaryHeader(this, memberContent);

32
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SearchWriter.java
View File

@ -25,17 +25,16 @@
package jdk.javadoc.internal.doclets.formats.html;
import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
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.HtmlAttr;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlId;
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.formats.html.markup.TagName;
import jdk.javadoc.internal.doclets.formats.html.markup.Text;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
/**
@ -46,32 +45,13 @@ public class SearchWriter extends HtmlDocletWriter {
/**
* Constructor to construct SearchWriter object.
* @param configuration the configuration
* @param filename file to be generated
*/
public SearchWriter(HtmlConfiguration configuration, DocPath filename) {
super(configuration, filename);
public SearchWriter(HtmlConfiguration configuration) {
super(configuration, DocPaths.SEARCH_PAGE);
}
/**
* Constructs the SearchWriter object and then use it to generate the search
* file. The name of the generated file is "search.html". The search file
* will get generated if and only if "-noindex" is not used on the command line.
*
* @param configuration the configuration
* @throws DocFileIOException if there is a problem while generating the documentation
*/
public static void generate(HtmlConfiguration configuration) throws DocFileIOException {
DocPath filename = DocPaths.SEARCH_PAGE;
SearchWriter searchWriter = new SearchWriter(configuration, filename);
searchWriter.generateSearchFile();
}
/**
* Generates the search file contents.
*
* @throws DocFileIOException if there is a problem while generating the documentation
*/
protected void generateSearchFile() throws DocFileIOException {
@Override
public void buildPage() throws DocFileIOException {
String title = resources.getText("doclet.Window_Search_title");
HtmlTree body = getBody(getWindowTitle(title));
ContentBuilder searchFileContent = new ContentBuilder();

7
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SerialFieldWriter.java
View File

@ -26,7 +26,6 @@
package jdk.javadoc.internal.doclets.formats.html;
import java.util.List;
import java.util.SortedSet;
import javax.lang.model.element.TypeElement;
import javax.lang.model.element.VariableElement;
@ -53,15 +52,11 @@ public class SerialFieldWriter extends FieldWriter {
super(writer, typeElement);
}
public SortedSet<VariableElement> members(TypeElement te) {
return utils.serializableFields(te);
}
protected Content getSerializableFieldsHeader() {
return HtmlTree.UL(HtmlStyle.blockList);
}
protected Content getFieldsContentHeader(boolean isLastContent) {
protected Content getFieldsContentHeader() {
return new HtmlTree(TagName.LI).setStyle(HtmlStyle.blockList);
}

2
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SerialMethodWriter.java
View File

@ -49,7 +49,7 @@ public class SerialMethodWriter extends MethodWriter {
return HtmlTree.UL(HtmlStyle.blockList);
}
protected Content getMethodsContentHeader(boolean isLastContent) {
protected Content getMethodsContentHeader() {
return new HtmlTree(TagName.LI);
}

36
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SerializedFormWriter.java
View File

@ -103,15 +103,11 @@ public class SerializedFormWriter extends SubWriterHolderWriter {
configuration.conditionalPages.add(HtmlConfiguration.ConditionalPage.SERIALIZED_FORM);
}
/**
* Build the serialized form.
*
* @throws DocletException if there is a problem while building the documentation
*/
void build() throws DocletException {
SortedSet<TypeElement> rootclasses = new TreeSet<>(utils.comparators.generalPurposeComparator());
rootclasses.addAll(configuration.getIncludedTypeElements());
if (!serialClassFoundToDocument(rootclasses)) {
@Override
public void buildPage() throws DocletException {
var rootClasses = new TreeSet<TypeElement>(utils.comparators.generalPurposeComparator());
rootClasses.addAll(configuration.getIncludedTypeElements());
if (!serialClassFoundToDocument(rootClasses)) {
//Nothing to document.
return;
}
@ -250,9 +246,9 @@ public class SerializedFormWriter extends SubWriterHolderWriter {
*/
protected void buildSerializableMethods(Content target) {
Content serializableMethodsHeader = methodWriter.getSerializableMethodsHeader();
for (var i = utils.serializationMethods(currentTypeElement).iterator(); i.hasNext(); ) {
currentMember = i.next();
Content methodsContent = methodWriter.getMethodsContentHeader(!i.hasNext());
for (var executableElement : utils.serializationMethods(currentTypeElement)) {
currentMember = executableElement;
Content methodsContent = methodWriter.getMethodsContentHeader();
buildMethodSubHeader(methodsContent);
buildDeprecatedMethodInfo(methodsContent);
@ -360,7 +356,7 @@ public class SerializedFormWriter extends SubWriterHolderWriter {
// information to be printed.
if (fieldWriter.shouldPrintOverview(ve)) {
Content serializableFieldsHeader = fieldWriter.getSerializableFieldsHeader();
Content fieldsOverviewContent = fieldWriter.getFieldsContentHeader(true);
Content fieldsOverviewContent = fieldWriter.getFieldsContentHeader();
fieldWriter.addMemberDeprecatedInfo(ve, fieldsOverviewContent);
if (!options.noComment()) {
fieldWriter.addMemberDescription(ve, fieldsOverviewContent);
@ -383,10 +379,10 @@ public class SerializedFormWriter extends SubWriterHolderWriter {
Collection<VariableElement> members = utils.serializableFields(currentTypeElement);
if (!members.isEmpty()) {
Content serializableFieldsHeader = fieldWriter.getSerializableFieldsHeader();
for (var i = members.iterator(); i.hasNext();) {
currentMember = i.next();
for (var member : members) {
currentMember = member;
if (!utils.definesSerializableFields(currentTypeElement)) {
Content fieldsContent = fieldWriter.getFieldsContentHeader(!i.hasNext());
Content fieldsContent = fieldWriter.getFieldsContentHeader();
buildFieldSubHeader(fieldsContent);
buildFieldDeprecationInfo(fieldsContent);
@ -451,7 +447,7 @@ public class SerializedFormWriter extends SubWriterHolderWriter {
for (SerialFieldTree tag : tags) {
if (tag.getName() == null || tag.getType() == null) // ignore malformed @serialField tags
continue;
Content fieldsContent = fieldWriter.getFieldsContentHeader(tag.equals(tags.last()));
Content fieldsContent = fieldWriter.getFieldsContentHeader();
TypeMirror type = ch.getReferencedType(tag);
fieldWriter.addMemberHeader(type, tag.getName().getName().toString(), fieldsContent);
fieldWriter.addMemberDescription(field, tag, fieldsContent);
@ -531,10 +527,10 @@ public class SerializedFormWriter extends SubWriterHolderWriter {
List<? extends SerialTree> serial = utils.getSerialTrees(element);
if (!serial.isEmpty()) {
// look for `@serial include|exclude`
String serialtext = Utils.toLowerCase(serial.get(0).toString());
if (serialtext.contains("exclude")) {
var serialText = Utils.toLowerCase(serial.get(0).toString());
if (serialText.contains("exclude")) {
return false;
} else if (serialtext.contains("include")) {
} else if (serialText.contains("include")) {
return true;
}
}

19
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SubWriterHolderWriter.java
View File

@ -42,7 +42,7 @@ import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
/**
* This abstract class exists to provide functionality needed in the
* the formatting of member information. Since AbstractSubWriter and its
* the formatting of member information. Since AbstractMemberWriter and its
* subclasses control this, they would be the logical place to put this.
* However, because each member type has its own subclass, subclassing
* can not be used effectively to change formatting. The concrete
@ -192,22 +192,6 @@ public abstract class SubWriterHolderWriter extends HtmlDocletWriter {
bodyContents.addMainContent(source);
}
/**
* Add the annotation content.
*
* @param source annotation content which will be added to the documentation
*/
public void addAnnotationContent(Content source) {
addClassContent(source);
}
/**
* {@return the member header}
*/
public Content getMemberHeader() {
return HtmlTree.UL(HtmlStyle.blockList);
}
/**
* Returns a list to be used for the list of summaries for members of a given kind.
*
@ -227,7 +211,6 @@ public abstract class SubWriterHolderWriter extends HtmlDocletWriter {
return HtmlTree.LI(content);
}
/**
* Returns a list to be used for the list of details for members of a given kind.
*

42
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SummaryListWriter.java
View File

@ -46,6 +46,11 @@ import jdk.javadoc.internal.doclets.toolkit.util.SummaryAPIListBuilder.SummaryEl
/**
* Base class for generating a summary page that lists elements with a common characteristic,
* such as deprecated elements, preview elements, and so on.
*
* Note: the use of "Summary" in this context is distinct from the use of "summary" in the
* context of {@link AbstractMemberWriter#buildSummary(Content)}.
*
* @param <B> a builder, to determine the elements to be included in the summary
*/
public abstract class SummaryListWriter<B extends SummaryAPIListBuilder> extends SubWriterHolderWriter {
@ -100,22 +105,37 @@ public abstract class SummaryListWriter<B extends SummaryAPIListBuilder> extends
this.builder = builder;
}
/**
* {@return the page mode to use}
*/
protected abstract PageMode getPageMode();
/**
* {@return the page descrition, for the {@code <meta>} element}
*/
protected abstract String getDescription();
/**
* {@return the heading for the page}
*/
protected abstract Content getHeadContent();
/**
* {@return the title for the page}
*/
protected abstract String getTitleKey();
/**
* Generate the API summary.
*
* @param pageMode page mode to use
* @param description page description
* @param headContent page heading content
* @param titleKey page title resource key
* @throws DocFileIOException if there is a problem writing the summary list
*/
protected void generateSummaryListFile(PageMode pageMode, String description,
Content headContent, String titleKey)
throws DocFileIOException {
HtmlTree body = getHeader(pageMode, titleKey);
@Override
public void buildPage() throws DocFileIOException {
HtmlTree body = getHeader(getPageMode(), getTitleKey());
Content content = new ContentBuilder();
var heading = HtmlTree.HEADING_TITLE(Headings.PAGE_TITLE_HEADING,
HtmlStyle.title, headContent);
HtmlStyle.title, getHeadContent());
content.add(HtmlTree.DIV(HtmlStyle.header, heading));
addContentSelectors(content);
content.add(HtmlTree.HEADING_TITLE(Headings.CONTENT_HEADING, contents.contentsHeading));
@ -147,7 +167,7 @@ public abstract class SummaryListWriter<B extends SummaryAPIListBuilder> extends
""").asContent());
bodyContents.setFooter(getFooter());
body.add(bodyContents);
printHtmlDocument(null, description, body);
printHtmlDocument(null, getDescription(), body);
}
/**
@ -181,9 +201,9 @@ public abstract class SummaryListWriter<B extends SummaryAPIListBuilder> extends
}
/**
* {@return the header for the API Summary listing}
* @param pageMode page mode to use
* @param titleKey page title resource key
* {@return the header for the API Summary listing}
*/
public HtmlTree getHeader(PageMode pageMode, String titleKey) {
String title = resources.getText(titleKey);

53
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/SystemPropertiesWriter.java
View File

@ -25,28 +25,32 @@
package jdk.javadoc.internal.doclets.formats.html;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.Map.Entry;
import java.util.TreeMap;
import java.util.WeakHashMap;
import java.util.stream.Collectors;
import javax.lang.model.element.Element;
import com.sun.source.doctree.DocTree;
import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
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.Text;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlStyle;
import jdk.javadoc.internal.doclets.formats.html.markup.HtmlTree;
import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
import jdk.javadoc.internal.doclets.formats.html.markup.Text;
import jdk.javadoc.internal.doclets.toolkit.DocletElement;
import jdk.javadoc.internal.doclets.toolkit.OverviewElement;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
import jdk.javadoc.internal.doclets.toolkit.util.IndexItem;
import javax.lang.model.element.Element;
import java.nio.file.Path;
import java.util.*;
import java.util.Map.Entry;
import static java.util.stream.Collectors.groupingBy;
import java.util.stream.Collectors;
import java.util.ArrayList;
/**
* Generates the file with the summary of all the system properties.
@ -62,37 +66,22 @@ public class SystemPropertiesWriter extends HtmlDocletWriter {
* Constructs SystemPropertiesWriter object.
*
* @param configuration The current configuration
* @param filename Path to the file which is getting generated.
*/
public SystemPropertiesWriter(HtmlConfiguration configuration, DocPath filename) {
super(configuration, filename);
public SystemPropertiesWriter(HtmlConfiguration configuration) {
super(configuration, DocPaths.SYSTEM_PROPERTIES, false);
}
public static void generate(HtmlConfiguration configuration) throws DocFileIOException {
generate(configuration, DocPaths.SYSTEM_PROPERTIES);
}
private static void generate(HtmlConfiguration configuration, DocPath fileName) throws DocFileIOException {
@Override
public void buildPage() throws DocFileIOException {
boolean hasSystemProperties = configuration.mainIndex != null
&& !configuration.mainIndex.getItems(DocTree.Kind.SYSTEM_PROPERTY).isEmpty();
if (!hasSystemProperties) {
// Cannot defer this check any further, because of the super() call
// that prints out notices on creating files, etc.
//
// There is probably a better place for this kind of checks (see how
// this is achieved in other "optional" pages, like Constant Values
// and Serialized Form).
return;
}
SystemPropertiesWriter systemPropertiesGen = new SystemPropertiesWriter(configuration, fileName);
systemPropertiesGen.buildSystemPropertiesPage();
configuration.conditionalPages.add(HtmlConfiguration.ConditionalPage.SYSTEM_PROPERTIES);
}
/**
* Prints all the system properties to the file.
*/
protected void buildSystemPropertiesPage() throws DocFileIOException {
writeGenerating();
configuration.conditionalPages.add(HtmlConfiguration.ConditionalPage.SYSTEM_PROPERTIES);
String title = resources.getText("doclet.systemProperties");
HtmlTree body = getBody(getWindowTitle(title));
Content mainContent = new ContentBuilder();

30
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TreeWriter.java
View File

@ -63,38 +63,18 @@ public class TreeWriter extends AbstractTreeWriter {
/**
* Constructor to construct TreeWriter object.
*
* @param configuration the current configuration of the doclet.
* @param filename String filename
* @param configuration the current configuration of the doclet
* @param classTree the tree being built.
*/
public TreeWriter(HtmlConfiguration configuration, DocPath filename, ClassTree classTree) {
super(configuration, filename, classTree);
public TreeWriter(HtmlConfiguration configuration, ClassTree classTree) {
super(configuration, DocPaths.OVERVIEW_TREE, classTree);
packages = configuration.packages;
classesOnly = packages.isEmpty();
this.bodyContents = new BodyContents();
}
/**
* Create a TreeWriter object and use it to generate the
* "overview-tree.html" file.
*
* @param configuration the configuration for this doclet
* @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 {
DocPath filename = DocPaths.OVERVIEW_TREE;
TreeWriter treegen = new TreeWriter(configuration, filename, classTree);
treegen.generateTreeFile();
}
/**
* Generate the interface hierarchy and class hierarchy.
*
* @throws DocFileIOException if there is a problem generating the overview tree page
*/
public void generateTreeFile() throws DocFileIOException {
@Override
public void buildPage() throws DocFileIOException {
HtmlTree body = getBody();
Content headContent = contents.hierarchyForAllPackages;
var heading = HtmlTree.HEADING(Headings.PAGE_TITLE_HEADING,

161
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/WriterFactory.java
View File

@ -26,16 +26,22 @@
package jdk.javadoc.internal.doclets.formats.html;
import java.util.List;
import javax.lang.model.element.Element;
import javax.lang.model.element.ModuleElement;
import javax.lang.model.element.PackageElement;
import javax.lang.model.element.TypeElement;
import jdk.javadoc.internal.doclets.toolkit.DocFileElement;
import jdk.javadoc.internal.doclets.toolkit.util.ClassTree;
import jdk.javadoc.internal.doclets.toolkit.util.ClassUseMapper;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.IndexBuilder;
import jdk.javadoc.internal.doclets.toolkit.util.VisibleMemberTable;
/**
* The factory that returns HTML writers.
* The factory that returns HTML writers, to be used to generate pages in the overall API documentation.
*/
public class WriterFactory {
@ -46,39 +52,152 @@ public class WriterFactory {
}
/**
* {@return a new {@link ConstantsSummaryWriter}}
* {@return a new writer for the page for a module}
*/
public ConstantsSummaryWriter newConstantsSummaryWriter() {
return new ConstantsSummaryWriter(configuration);
}
/**
* {@return a new {@link PackageWriter}}
*/
public PackageWriter newPackageWriter(PackageElement packageElement) {
return new PackageWriter(configuration, packageElement);
}
/**
* {@return a new {@link ModuleWriter}}
*/
public ModuleWriter newModuleWriter(ModuleElement mdle) {
public HtmlDocletWriter newModuleWriter(ModuleElement mdle) {
return new ModuleWriter(configuration, mdle);
}
/**
* {@return a new {@link ClassWriter}}
* {@return a new writer for the "module index" page}
*/
public ClassWriter newClassWriter(TypeElement typeElement, ClassTree classTree) {
public HtmlDocletWriter newModuleIndexWriter() {
return new ModuleIndexWriter(configuration);
}
/**
* {@return a new writer for the page for a package}
*/
public HtmlDocletWriter newPackageWriter(PackageElement packageElement) {
return new PackageWriter(configuration, packageElement);
}
/**
* {@return a new writer for the "package index" page}
*/
public HtmlDocletWriter newPackageIndexWriter() {
return new PackageIndexWriter(configuration);
}
/**
* {@return a new writer for the "package use" page for a package}
*/
public HtmlDocletWriter newPackageUseWriter(PackageElement packageElement, ClassUseMapper mapper) {
return new PackageUseWriter(configuration, mapper, packageElement);
}
/**
* {@return a new writer for the page for a class or other type element}
*/
public HtmlDocletWriter newClassWriter(TypeElement typeElement, ClassTree classTree) {
return new ClassWriter(configuration, typeElement, classTree);
}
/**
* {@return a new {@link SerializedFormWriter}}
* {@return a new writer for the "class use" page for a class or other type element}
*/
public SerializedFormWriter newSerializedFormWriter() {
public HtmlDocletWriter newClassUseWriter(TypeElement typeElement, ClassUseMapper mapper) {
return new ClassUseWriter(configuration, mapper, typeElement);
}
/**
* {@return a new writer for the list of "all classes"}
*/
public HtmlDocletWriter newAllClassesIndexWriter(IndexBuilder indexBuilder) {
return new AllClassesIndexWriter(configuration, indexBuilder);
}
/**
* {@return a new writer for the list of "all packages"}
*/
public HtmlDocletWriter newAllPackagesIndexWriter() {
return new AllPackagesIndexWriter(configuration);
}
/**
* {@return a new writer for the "constants summary" page}
*/
public HtmlDocletWriter newConstantsSummaryWriter() {
return new ConstantsSummaryWriter(configuration);
}
/**
* {@return a new writer for the page giving the API that has been deprecated in recent releases}
*/
public HtmlDocletWriter newDeprecatedListWriter() {
return new DeprecatedListWriter(configuration);
}
/**
* {@return a new writer for a "doc-file" page}
*/
public HtmlDocletWriter newDocFileWriter(DocPath path, DocFileElement dfElement) {
return new DocFilesHandler.DocFileWriter(configuration, path, dfElement);
}
/**
* {@return a new writer for the page listing external specifications referenced in the API}
*/
public HtmlDocletWriter newExternalSpecsWriter() {
return new ExternalSpecsWriter(configuration);
}
/**
* {@return a new writer for the "help" page}
*/
public HtmlDocletWriter newHelpWriter() {
return new HelpWriter(configuration);
}
/**
* {@return a new writer for an "index" page}
*/
public HtmlDocletWriter newIndexWriter(DocPath path, List<Character> allFirstCharacters, List<Character> displayFirstCharacters) {
return new IndexWriter(configuration, path, allFirstCharacters, displayFirstCharacters);
}
/**
* {@return a new writer for the list of new API in recent releases}
*/
public HtmlDocletWriter newNewAPIListWriter() {
return new NewAPIListWriter(configuration);
}
/**
* {@return a new writer for the list of preview API in this release}
*/
public HtmlDocletWriter newPreviewListWriter() {
return new PreviewListWriter(configuration);
}
/**
* {@return a new writer for the "search" page}
*/
public HtmlDocletWriter newSearchWriter() {
return new SearchWriter(configuration);
}
/**
* {@return a new writer for the page giving the serialized forms of classes and other type elements}
*/
public HtmlDocletWriter newSerializedFormWriter() {
return new SerializedFormWriter(configuration);
}
/**
* {@return a new writer for the page listing system properties referenced in the API}
*/
public HtmlDocletWriter newSystemPropertiesWriter() {
return new SystemPropertiesWriter(configuration);
}
/**
* {@return a new writer for the page showing the hierarchy of classes and their superclasses}
*/
public HtmlDocletWriter newTreeWriter(ClassTree classTree) {
return new TreeWriter(configuration, classTree);
}
/**
* Returns a new member writer for the members of a given class and given kind.
*

1
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Entity.java
View File

@ -71,7 +71,6 @@ public class Entity extends Content {
return 1;
}
/**
* Escapes the special HTML characters in a given string using the appropriate
* entities.

1
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/Head.java
View File

@ -304,7 +304,6 @@ public class Head extends Content {
return head;
}
private Comment getGeneratedBy(boolean timestamp, ZonedDateTime buildDate) {
String text = "Generated by javadoc"; // marker string, deliberately not localized
text += " (" + docletVersion.feature() + ")";

30
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/DocFileElement.java
View File

@ -38,27 +38,43 @@ import jdk.javadoc.internal.doclets.toolkit.util.Utils;
*/
public class DocFileElement implements DocletElement {
private final Element element;
private final PackageElement packageElement;
private final FileObject fo;
/**
* Creates a pseudo-element that wraps a {@code doc-files} HTML file.
*
* @param utils the standard utilities class
* @param element the module element or package element that "owns" the {@code doc-files} subdirectory
* @param fo the file object
*
* @throws IllegalArgumentException if the given element is not a module element or package element
*/
public DocFileElement(Utils utils, Element element, FileObject fo) {
this.element = element;
this.fo = fo;
switch(element.getKind()) {
case MODULE:
switch (element.getKind()) {
case MODULE -> {
ModuleElement moduleElement = (ModuleElement) element;
packageElement = utils.elementUtils.getPackageElement(moduleElement, "");
break;
}
case PACKAGE:
case PACKAGE ->
packageElement = (PackageElement) element;
break;
default:
throw new AssertionError("unknown kind: " + element.getKind());
default -> throw new IllegalArgumentException(element.getKind() + ":" + element);
}
}
/**
* {@return the element that "owns" the {@code doc-files} directory}
*/
public Element getElement() {
return element;
}
@Override
public PackageElement getPackageElement() {
return packageElement;

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

@ -380,6 +380,11 @@ public class Utils {
.compareTo(SourceVersion.RELEASE_8) >= 0;
}
public boolean isFunctionalInterface(TypeElement typeElement) {
return typeElement.getAnnotationMirrors().stream()
.anyMatch(this::isFunctionalInterface);
}
public boolean isUndocumentedEnclosure(TypeElement enclosingTypeElement) {
return (isPackagePrivate(enclosingTypeElement) || isPrivate(enclosingTypeElement)
|| hasHiddenTag(enclosingTypeElement))