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

8263198: javadoc HELP page

Browse Source 
Reviewed-by: hannesw
This commit is contained in:
Jonathan Gibbons 2021-03-24 19:51:35 +00:00
parent 5ca5962d8f
commit 3e751a5a9c
14 changed files with 489 additions and 226 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -106,6 +106,7 @@ public class Contents {
public final Content functionalInterface;
public final Content functionalInterfaceMessage;
public final Content helpLabel;
public final Content helpSubNavLabel;
public final Content hierarchyForAllPackages;
public final Content implementation;
public final Content implementingClassesLabel;
@ -130,6 +131,8 @@ public class Contents {
public final Content navConstructor;
public final Content navEnum;
public final Content navField;
public final Content navHelpNavigation;
public final Content navHelpPages;
public final Content navMethod;
public final Content navModuleDescription;
public final Content navModules;
@ -252,6 +255,7 @@ public class Contents {
functionalInterface = getContent("doclet.Functional_Interface");
functionalInterfaceMessage = getContent("doclet.Functional_Interface_Message");
helpLabel = getContent("doclet.Help");
helpSubNavLabel = getContent("doclet.Help_Sub_Nav");
hierarchyForAllPackages = getContent("doclet.Hierarchy_For_All_Packages");
implementation = getContent("doclet.Implementation");
implementingClassesLabel = getContent("doclet.Implementing_Classes");
@ -276,6 +280,8 @@ public class Contents {
navConstructor = getContent("doclet.navConstructor");
navEnum = getContent("doclet.navEnum");
navField = getContent("doclet.navField");
navHelpNavigation = getContent("doclet.navNavigation");
navHelpPages = getContent("doclet.navPages");
navMethod = getContent("doclet.navMethod");
navModuleDescription = getContent("doclet.navModuleDescription");
navModules = getContent("doclet.navModules");

8
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Headings.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 1998, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 1998, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -47,6 +47,12 @@ class Headings {
*/
static final TagName CONTENT_HEADING = TagName.H2;
/**
* Standard third-level heading for sundry pages that do
* not have their own page group.
*/
static final TagName SUB_HEADING = TagName.H3;
/**
* Headings for the page for a module declaration.
*/

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

@ -29,6 +29,7 @@ import java.util.List;
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.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;
@ -36,6 +37,7 @@ import jdk.javadoc.internal.doclets.formats.html.Navigation.PageMode;
import jdk.javadoc.internal.doclets.formats.html.markup.Text;
import jdk.javadoc.internal.doclets.toolkit.Content;
import jdk.javadoc.internal.doclets.toolkit.util.DocFileIOException;
import jdk.javadoc.internal.doclets.toolkit.util.DocLink;
import jdk.javadoc.internal.doclets.toolkit.util.DocPath;
import jdk.javadoc.internal.doclets.toolkit.util.DocPaths;
@ -57,6 +59,11 @@ public class HelpWriter extends HtmlDocletWriter {
{"HM.cK", "\"java.util.HashMap.containsKey(Object)\""}
};
Content overviewLink;
Content indexLink;
Content allClassesLink;
Content allPackagesLink;
/**
* Constructor to construct HelpWriter object.
* @param configuration the configuration
@ -65,6 +72,15 @@ public class HelpWriter extends HtmlDocletWriter {
public HelpWriter(HtmlConfiguration configuration,
DocPath filename) {
super(configuration, filename);
// yes, INDEX is correct in the following line
overviewLink = links.createLink(DocPaths.INDEX, resources.getText("doclet.Overview"));
allPackagesLink = links.createLink(DocPaths.ALLPACKAGES_INDEX, resources.getText("doclet.All_Packages"));
allClassesLink = links.createLink(DocPaths.ALLCLASSES_INDEX, resources.getText("doclet.All_Classes"));
DocPath dp = options.splitIndex()
? DocPaths.INDEX_FILES.resolve(DocPaths.indexN(1))
: DocPaths.INDEX_ALL;
indexLink = links.createLink(dp, resources.getText("doclet.Index"));
}
/**
@ -100,186 +116,72 @@ public class HelpWriter extends HtmlDocletWriter {
}
/**
* Add the help file contents from the resource file to the content tree. While adding the
* help file contents it also keeps track of user options. If "-notree"
* is used, then the "overview-tree.html" will not get added and hence
* help information also will not get added.
* Adds the help file contents from the resource file to the content tree. While adding the
* help file contents it also keeps track of user options.
*
* @param contentTree the content tree to which the help file contents will be added
* The general organization is:
* <ul>
* <li>Heading, and TOC
* <li>Navigation help
* <li>Page-specific help
* </ul>
*/
protected void addHelpFileContents(Content contentTree) {
// Heading
Content heading = HtmlTree.HEADING(Headings.PAGE_TITLE_HEADING, HtmlStyle.title,
getContent("doclet.help.main_heading"));
Content div = HtmlTree.DIV(HtmlStyle.header, heading);
Content intro = HtmlTree.DIV(HtmlStyle.subTitle,
getContent("doclet.help.intro"));
div.add(intro);
contentTree.add(div);
HtmlTree mainTOC = new HtmlTree(TagName.UL).setStyle(HtmlStyle.helpTOC);
contentTree.add(HtmlTree.HEADING(Headings.PAGE_TITLE_HEADING, HtmlStyle.title,
getContent("doclet.help.main_heading")))
.add(mainTOC)
.add(new HtmlTree(TagName.HR))
.add(getNavigationSection(mainTOC))
.add(new HtmlTree(TagName.HR))
.add(getPageKindSection(mainTOC))
.add(new HtmlTree(TagName.HR))
.add(HtmlTree.SPAN(HtmlStyle.helpFootnote,
getContent("doclet.help.footnote")));
}
/**
* Creates the navigation help, adding an entry into the main table-of-contents.
*
* The general organization is:
* <ul>
* <li>General notes
* <li>Search
* </ul>
*
* @param mainTOC the main table-of-contents
*
* @return the content containing the help
*/
private Content getNavigationSection(HtmlTree mainTOC) {
Content content = new ContentBuilder();
Content navHeading = contents.getContent("doclet.help.navigation.head");
HtmlTree navSection = HtmlTree.DIV(HtmlStyle.subTitle)
.add(HtmlTree.HEADING(Headings.CONTENT_HEADING, navHeading).setId(HtmlIds.HELP_NAVIGATION))
.add(contents.getContent("doclet.help.navigation.intro", overviewLink));
if (options.createIndex()) {
Content links = new ContentBuilder();
if (!configuration.packages.isEmpty()) {
links.add(allPackagesLink);
links.add(", ");
}
links.add(allClassesLink);
navSection.add(" ")
.add(contents.getContent("doclet.help.navigation.index", indexLink, links));
}
content.add(navSection);
HtmlTree subTOC = new HtmlTree(TagName.UL).setStyle(HtmlStyle.helpSubTOC);
HtmlTree section;
// Overview
if (options.createOverview()) {
section = newHelpSection(contents.overviewLabel);
String overviewKey = configuration.showModules
? "doclet.help.overview.modules.body"
: "doclet.help.overview.packages.body";
Content overviewLink = links.createLink(
DocPaths.INDEX, resources.getText("doclet.Overview"));
section.add(HtmlTree.P(getContent(overviewKey, overviewLink)));
contentTree.add(section);
}
// Module
if (configuration.showModules) {
section = newHelpSection(contents.moduleLabel);
Content moduleIntro = getContent("doclet.help.module.intro");
Content modulePara = HtmlTree.P(moduleIntro);
section.add(modulePara)
.add(newHelpSectionList(
contents.packagesLabel,
contents.modulesLabel,
contents.servicesLabel));
contentTree.add(section);
}
// Package
section = newHelpSection(contents.packageLabel)
.add(HtmlTree.P(getContent("doclet.help.package.intro")))
.add(newHelpSectionList(
contents.interfaces,
contents.classes,
contents.enums,
contents.exceptions,
contents.errors,
contents.annotationTypes));
contentTree.add(section);
// Class/interface
section = newHelpSection(getContent("doclet.help.class_interface.head"))
.add(HtmlTree.P(getContent("doclet.help.class_interface.intro")))
.add(newHelpSectionList(
getContent("doclet.help.class_interface.inheritance_diagram"),
getContent("doclet.help.class_interface.subclasses"),
getContent("doclet.help.class_interface.subinterfaces"),
getContent("doclet.help.class_interface.implementations"),
getContent("doclet.help.class_interface.declaration"),
getContent("doclet.help.class_interface.description")))
.add(new HtmlTree(TagName.BR))
.add(newHelpSectionList(
contents.nestedClassSummary,
contents.fieldSummaryLabel,
contents.propertySummaryLabel,
contents.constructorSummaryLabel,
contents.methodSummary))
.add(new HtmlTree(TagName.BR))
.add(newHelpSectionList(
contents.fieldDetailsLabel,
contents.propertyDetailsLabel,
contents.constructorDetailsLabel,
contents.methodDetailLabel))
.add(HtmlTree.P(getContent("doclet.help.class_interface.summary")));
contentTree.add(section);
// Annotation Types
section = newHelpSection(contents.annotationType)
.add(HtmlTree.P(getContent("doclet.help.annotation_type.intro")))
.add(newHelpSectionList(
getContent("doclet.help.annotation_type.declaration"),
getContent("doclet.help.annotation_type.description"),
contents.annotateTypeRequiredMemberSummaryLabel,
contents.annotateTypeOptionalMemberSummaryLabel,
contents.annotationTypeMemberDetail));
contentTree.add(section);
// Enums
section = newHelpSection(contents.enum_)
.add(HtmlTree.P(getContent("doclet.help.enum.intro")))
.add(newHelpSectionList(
getContent("doclet.help.enum.declaration"),
getContent("doclet.help.enum.definition"),
contents.enumConstantSummary,
contents.enumConstantDetailLabel));
contentTree.add(section);
// Class Use
if (options.classUse()) {
section = newHelpSection(getContent("doclet.help.use.head"))
.add(HtmlTree.P(getContent("doclet.help.use.body")));
contentTree.add(section);
}
// Tree
if (options.createTree()) {
section = newHelpSection(getContent("doclet.help.tree.head"));
Content treeIntro = getContent("doclet.help.tree.intro",
links.createLink(DocPaths.OVERVIEW_TREE, resources.getText("doclet.Class_Hierarchy")),
HtmlTree.CODE(Text.of("java.lang.Object")));
section.add(HtmlTree.P(treeIntro))
.add(newHelpSectionList(
getContent("doclet.help.tree.overview"),
getContent("doclet.help.tree.package")));
contentTree.add(section);
}
// Deprecated
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.DEPRECATED)) {
section = newHelpSection(contents.deprecatedAPI);
Content deprBody = getContent("doclet.help.deprecated.body",
links.createLink(DocPaths.DEPRECATED_LIST, resources.getText("doclet.Deprecated_API")));
section.add(HtmlTree.P(deprBody));
contentTree.add(section);
}
// Preview
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.PREVIEW)) {
section = newHelpSection(contents.previewAPI);
Content previewBody = getContent("doclet.help.preview.body",
links.createLink(DocPaths.PREVIEW_LIST, contents.previewAPI));
section.add(HtmlTree.P(previewBody));
contentTree.add(section);
}
// Index
if (options.createIndex()) {
DocPath dp = options.splitIndex()
? DocPaths.INDEX_FILES.resolve(DocPaths.indexN(1))
: DocPaths.INDEX_ALL;
Content indexLink = links.createLink(dp, resources.getText("doclet.Index"));
section = newHelpSection(getContent("doclet.help.index.head"))
.add(HtmlTree.P(getContent("doclet.help.index.body", indexLink)));
contentTree.add(section);
}
// Serialized Form
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.SERIALIZED_FORM)) {
section = newHelpSection(contents.serializedForm)
.add(HtmlTree.P(getContent("doclet.help.serial_form.body")));
contentTree.add(section);
}
// Constant Field Values
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.CONSTANT_VALUES)) {
section = newHelpSection(contents.constantsSummaryTitle);
Content constantsBody = getContent("doclet.help.constants.body",
links.createLink(DocPaths.CONSTANT_VALUES, resources.getText("doclet.Constants_Summary")));
section.add(HtmlTree.P(constantsBody));
contentTree.add(section);
}
// System Properties
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.SYSTEM_PROPERTIES)) {
section = newHelpSection(contents.systemPropertiesLabel);
Content sysPropsBody = getContent("doclet.help.systemProperties.body",
links.createLink(DocPaths.SYSTEM_PROPERTIES, resources.getText("doclet.systemProperties")));
section.add(HtmlTree.P(sysPropsBody));
contentTree.add(section);
}
// Search
if (options.createIndex()) {
section = newHelpSection(getContent("doclet.help.search.head"));
section = newHelpSection(getContent("doclet.help.search.head"), subTOC, HtmlIds.HELP_SEARCH);
Content searchIntro = HtmlTree.P(getContent("doclet.help.search.intro"));
Content searchExamples = new HtmlTree(TagName.UL).setStyle(HtmlStyle.helpSectionList);
for (String[] example : SEARCH_EXAMPLES) {
@ -294,12 +196,217 @@ public class HelpWriter extends HtmlDocletWriter {
section.add(searchIntro)
.add(searchExamples)
.add(searchRefer);
contentTree.add(section);
navSection.add(section);
}
contentTree.add(new HtmlTree(TagName.HR))
.add(HtmlTree.SPAN(HtmlStyle.helpFootnote,
getContent("doclet.help.footnote")));
mainTOC.add(HtmlTree.LI(new ContentBuilder(
links.createLink(DocLink.fragment(HtmlIds.HELP_NAVIGATION.name()), navHeading),
Text.of(": "), subTOC)));
return content;
}
/**
* Creates the page-specific help, adding an entry into the main table-of-contents.
*
* The general organization is:
* <ul>
* <li>Overview
* <li>Declaration pages: module, package, classes
* <li>Derived info for declarations: use and tree
* <li>General summary info: deprecated, preview
* <li>Detailed summary info: constant values, serialized form, system properties
* <li>Index info: all packages, all classes, full index
* </ul>
*
* @param mainTOC the main table-of-contents
*
* @return the content containing the help
*/
private Content getPageKindSection(HtmlTree mainTOC) {
Content pageKindsHeading = contents.getContent("doclet.help.page_kinds.head");
HtmlTree pageKindsSection = HtmlTree.DIV(HtmlStyle.subTitle)
.add(HtmlTree.HEADING(Headings.CONTENT_HEADING, pageKindsHeading).setId(HtmlIds.HELP_PAGES))
.add(contents.getContent("doclet.help.page_kinds.intro"));
HtmlTree subTOC = new HtmlTree(TagName.UL).setStyle(HtmlStyle.helpSubTOC);
HtmlTree section;
// Overview
if (options.createOverview()) {
section = newHelpSection(contents.overviewLabel, PageMode.OVERVIEW, subTOC);
String overviewKey = configuration.showModules
? "doclet.help.overview.modules.body"
: "doclet.help.overview.packages.body";
section.add(HtmlTree.P(getContent(overviewKey, overviewLink)));
pageKindsSection.add(section);
}
// Module
if (configuration.showModules) {
section = newHelpSection(contents.moduleLabel, PageMode.MODULE, subTOC);
Content moduleIntro = getContent("doclet.help.module.intro");
Content modulePara = HtmlTree.P(moduleIntro);
section.add(modulePara)
.add(newHelpSectionList(
contents.packagesLabel,
contents.modulesLabel,
contents.servicesLabel));
pageKindsSection.add(section);
}
// Package
section = newHelpSection(contents.packageLabel, PageMode.PACKAGE, subTOC)
.add(HtmlTree.P(getContent("doclet.help.package.intro")))
.add(newHelpSectionList(
contents.interfaces,
contents.classes,
contents.enums,
contents.exceptions,
contents.errors,
contents.annotationTypes));
pageKindsSection.add(section);
// Class/interface
Content notes = new ContentBuilder(
HtmlTree.SPAN(HtmlStyle.helpNote, getContent("doclet.help.class_interface.note")),
Text.of(" "),
getContent("doclet.help.class_interface.anno"),
Text.of(" "),
getContent("doclet.help.class_interface.enum"),
Text.of(" "),
getContent("doclet.help.class_interface.record"),
Text.of(" "),
getContent("doclet.help.class_interface.property"));
section = newHelpSection(getContent("doclet.help.class_interface.head"), PageMode.CLASS, subTOC)
.add(HtmlTree.P(getContent("doclet.help.class_interface.intro")))
.add(newHelpSectionList(
getContent("doclet.help.class_interface.inheritance_diagram"),
getContent("doclet.help.class_interface.subclasses"),
getContent("doclet.help.class_interface.subinterfaces"),
getContent("doclet.help.class_interface.implementations"),
getContent("doclet.help.class_interface.declaration"),
getContent("doclet.help.class_interface.description")))
.add(new HtmlTree(TagName.BR))
.add(newHelpSectionList(
contents.nestedClassSummary,
contents.enumConstantSummary,
contents.fieldSummaryLabel,
contents.propertySummaryLabel,
contents.constructorSummaryLabel,
contents.methodSummary,
contents.annotateTypeRequiredMemberSummaryLabel,
contents.annotateTypeOptionalMemberSummaryLabel))
.add(new HtmlTree(TagName.BR))
.add(newHelpSectionList(
contents.enumConstantDetailLabel,
contents.fieldDetailsLabel,
contents.propertyDetailsLabel,
contents.constructorDetailsLabel,
contents.methodDetailLabel,
contents.annotationTypeMemberDetail))
.add(HtmlTree.P(notes))
.add(HtmlTree.P(getContent("doclet.help.class_interface.member_order")));
pageKindsSection.add(section);
section = newHelpSection(getContent("doclet.help.other_files.head"), PageMode.DOC_FILE, subTOC)
.add(HtmlTree.P(getContent("doclet.help.other_files.body")));
pageKindsSection.add(section);
// Class Use
if (options.classUse()) {
section = newHelpSection(getContent("doclet.help.use.head"), PageMode.USE, subTOC)
.add(HtmlTree.P(getContent("doclet.help.use.body")));
pageKindsSection.add(section);
}
// Tree
if (options.createTree()) {
section = newHelpSection(getContent("doclet.help.tree.head"), PageMode.TREE, subTOC);
Content treeIntro = getContent("doclet.help.tree.intro",
links.createLink(DocPaths.OVERVIEW_TREE, resources.getText("doclet.Class_Hierarchy")),
HtmlTree.CODE(Text.of("java.lang.Object")));
section.add(HtmlTree.P(treeIntro))
.add(newHelpSectionList(
getContent("doclet.help.tree.overview"),
getContent("doclet.help.tree.package")));
pageKindsSection.add(section);
}
// Deprecated
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.DEPRECATED)) {
section = newHelpSection(contents.deprecatedAPI, PageMode.DEPRECATED, subTOC);
Content deprBody = getContent("doclet.help.deprecated.body",
links.createLink(DocPaths.DEPRECATED_LIST, resources.getText("doclet.Deprecated_API")));
section.add(HtmlTree.P(deprBody));
pageKindsSection.add(section);
}
// Preview
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.PREVIEW)) {
section = newHelpSection(contents.previewAPI, PageMode.PREVIEW, subTOC);
Content previewBody = getContent("doclet.help.preview.body",
links.createLink(DocPaths.PREVIEW_LIST, contents.previewAPI));
section.add(HtmlTree.P(previewBody));
pageKindsSection.add(section);
}
// Constant Field Values
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.CONSTANT_VALUES)) {
section = newHelpSection(contents.constantsSummaryTitle, PageMode.CONSTANT_VALUES, subTOC);
Content constantsBody = getContent("doclet.help.constants.body",
links.createLink(DocPaths.CONSTANT_VALUES, resources.getText("doclet.Constants_Summary")));
section.add(HtmlTree.P(constantsBody));
pageKindsSection.add(section);
}
// Serialized Form
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.SERIALIZED_FORM)) {
section = newHelpSection(contents.serializedForm, PageMode.SERIALIZED_FORM, subTOC)
.add(HtmlTree.P(getContent("doclet.help.serial_form.body")));
pageKindsSection.add(section);
}
// System Properties
if (configuration.conditionalPages.contains(HtmlConfiguration.ConditionalPage.SYSTEM_PROPERTIES)) {
section = newHelpSection(contents.systemPropertiesLabel, PageMode.SYSTEM_PROPERTIES, subTOC);
Content sysPropsBody = getContent("doclet.help.systemProperties.body",
links.createLink(DocPaths.SYSTEM_PROPERTIES, resources.getText("doclet.systemProperties")));
section.add(HtmlTree.P(sysPropsBody));
pageKindsSection.add(section);
}
// Index
if (options.createIndex()) {
if (!configuration.packages.isEmpty()) {
section = newHelpSection(getContent("doclet.help.all_packages.head"), PageMode.ALL_PACKAGES, subTOC)
.add(HtmlTree.P(getContent("doclet.help.all_packages.body", allPackagesLink)));
pageKindsSection.add(section);
}
section = newHelpSection(getContent("doclet.help.all_classes.head"), PageMode.ALL_CLASSES, subTOC)
.add(HtmlTree.P(getContent("doclet.help.all_classes.body", allClassesLink)));
pageKindsSection.add(section);
Content links = new ContentBuilder();
if (!configuration.packages.isEmpty()) {
links.add(allPackagesLink);
links.add(", ");
}
links.add(allClassesLink);
section = newHelpSection(getContent("doclet.help.index.head"), PageMode.INDEX, subTOC)
.add(HtmlTree.P(getContent("doclet.help.index.body", indexLink, links)));
pageKindsSection.add(section);
}
mainTOC.add(HtmlTree.LI(new ContentBuilder(
links.createLink(DocLink.fragment(HtmlIds.HELP_PAGES.name()), pageKindsHeading),
Text.of(": "), subTOC)));
return pageKindsSection;
}
private Content getContent(String key) {
@ -314,9 +421,17 @@ public class HelpWriter extends HtmlDocletWriter {
return contents.getContent(key, arg1, arg2);
}
private HtmlTree newHelpSection(Content headingContent) {
private HtmlTree newHelpSection(Content headingContent, HtmlTree toc, HtmlId id) {
Content link = links.createLink(DocLink.fragment(id.name()), headingContent);
toc.add(HtmlTree.LI(link));
return HtmlTree.SECTION(HtmlStyle.helpSection,
HtmlTree.HEADING(Headings.CONTENT_HEADING, headingContent));
HtmlTree.HEADING(Headings.SUB_HEADING, headingContent))
.setId(id);
}
private HtmlTree newHelpSection(Content headingContent, Navigation.PageMode pm, HtmlTree toc) {
return newHelpSection(headingContent, toc, htmlIds.forPage(pm));
}
private HtmlTree newHelpSectionList(Content first, Content... rest) {

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

@ -26,6 +26,7 @@
package jdk.javadoc.internal.doclets.formats.html;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import javax.lang.model.element.Element;
import javax.lang.model.element.ExecutableElement;
@ -77,6 +78,9 @@ public class HtmlIds {
static final HtmlId FIELD_DETAIL = HtmlId.of("field-detail");
static final HtmlId FIELD_SUMMARY = HtmlId.of("field-summary");
static final HtmlId FOR_REMOVAL = HtmlId.of("for-removal");
static final HtmlId HELP_NAVIGATION = HtmlId.of("help-navigation");
static final HtmlId HELP_PAGES = HtmlId.of("help-pages");
static final HtmlId HELP_SEARCH = HtmlId.of("help-search");
static final HtmlId METHOD_DETAIL = HtmlId.of("method-detail");
static final HtmlId METHOD_SUMMARY = HtmlId.of("method-summary");
static final HtmlId METHOD_SUMMARY_TABLE = HtmlId.of("method-summary-table");
@ -441,6 +445,13 @@ public class HtmlIds {
}
/**
* Returns an id for the "preview" section for an element.
*
* @param el the element
*
* @return the id
*/
public HtmlId forPreviewSection(Element el) {
return HtmlId.of("preview-" + switch (el.getKind()) {
case CONSTRUCTOR, METHOD -> forMember((ExecutableElement) el).name();
@ -448,4 +459,15 @@ public class HtmlIds {
default -> utils.getFullyQualifiedName(el, false);
});
}
/**
* Returns an id for the entry on the HELP page for a kind of generated page.
*
* @param page the kind of page
*
* @return the id
*/
public HtmlId forPage(Navigation.PageMode page) {
return HtmlId.of(page.name().toLowerCase(Locale.ROOT).replace("_", "-"));
}
}

18
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/Navigation.java
View File

@ -387,6 +387,7 @@ public class Navigation {
addListToNav(listContents, tree);
}
break;
case MODULE:
if (displaySummaryModuleDescLink) {
addContentToList(listContents,
@ -419,6 +420,18 @@ public class Navigation {
addListToNav(listContents, tree);
}
break;
case HELP:
addContentToList(listContents,
links.createLink(HtmlIds.HELP_NAVIGATION, contents.navHelpNavigation));
addContentToList(listContents,
links.createLink(HtmlIds.HELP_PAGES, contents.navHelpPages));
Content li = HtmlTree.LI(contents.helpSubNavLabel);
li.add(Entity.NO_BREAK_SPACE);
tree.add(li);
addListToNav(listContents, tree);
break;
default:
break;
}
@ -601,7 +614,7 @@ public class Navigation {
for (VisibleMemberTable.Kind kind : detailSet) {
AbstractMemberWriter writer
= ((AbstractMemberWriter) memberSummaryBuilder.
getMemberSummaryWriter(kind));
getMemberSummaryWriter(kind));
if (kind == ENUM_CONSTANTS && !configuration.utils.isEnum(typeElement)) {
continue;
}
@ -884,7 +897,8 @@ public class Navigation {
DocFile file = DocFile.createFileForInput(configuration, helpfile);
helpfilenm = DocPath.create(file.getName());
}
tree.add(HtmlTree.LI(links.createLink(pathToRoot.resolve(helpfilenm),
tree.add(HtmlTree.LI(links.createLink(
new DocLink(pathToRoot.resolve(helpfilenm), htmlIds.forPage(documentedPage).name()),
contents.helpLabel, "")));
}
}

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

@ -60,9 +60,6 @@ public enum HtmlStyle {
deprecationComment,
descfrmTypeLabel,
externalLink,
helpFootnote,
helpSection,
helpSectionList,
hierarchy,
horizontal,
implementationLabel,
@ -716,7 +713,44 @@ public enum HtmlStyle {
/**
* The class of the {@code body} element for the page for the class hierarchy.
*/
treePage;
treePage,
//</editor-fold>
//<editor-fold desc="page styles for <body> elements">
//
// The following constants are used for the class of the {@code <body>} element
// for the corresponding pages.
/**
* The class of the footnote at the bottom of the page.
*/
helpFootnote,
/**
* The class of the "Note:" prefix.
*/
helpNote,
/**
* The class of each subsection in the page.
*/
helpSection,
/**
* The class of lists in a subsection in the page.
*/
helpSectionList,
/**
* The class of the top level list for the table of contents for the page.
*/
helpTOC("help-toc"),
/**
* The class of the second-level lists in the table of contents for the page.
*/
helpSubTOC("help-subtoc");
//</editor-fold>
private final String cssName;

91
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties
View File

@ -53,6 +53,7 @@ doclet.Href_Class_Or_Interface_Title=class or interface in {0}
doclet.Summary=Summary:
doclet.Detail=Detail:
doclet.Module_Sub_Nav=Module:
doclet.Help_Sub_Nav=Help:
doclet.navModuleDescription=Description
doclet.navModules=Modules
doclet.navPackages=Packages
@ -66,6 +67,8 @@ doclet.navProperty=Property
doclet.navEnum=Enum Constants
doclet.navConstructor=Constr
doclet.navMethod=Method
doclet.navNavigation=Navigation
doclet.navPages=Pages
doclet.not.exhaustive=(not exhaustive)
doclet.Index=Index
doclet.Window_Single_Index=Index
@ -143,28 +146,42 @@ doclet.Window_Source_title=Source code
doclet.Window_Help_title=API Help
doclet.help.main_heading=\
How This API Document Is Organized
doclet.help.intro=\
This API (Application Programming Interface) document has pages corresponding to the items in \
the navigation bar, described as follows.
JavaDoc Help
doclet.help.navigation.head=\
Navigation
# 0: link to the Overview page
doclet.help.navigation.intro=\
Starting from the {0} page, you can browse the documentation using the links \
in each page, and in the navigation bar at the top of each page.
# 0: link to the Index; 1: short list of links
doclet.help.navigation.index=\
The {0} and Search box allow you to navigate to specific declarations and summary pages, \
including: {1}
doclet.help.page_kinds.head=\
Kinds of Pages
doclet.help.page_kinds.intro=\
The following sections describe the different kinds of pages in this collection.
# 0: link to the Overview page
doclet.help.overview.modules.body=\
The {0} page is the front page of this API document and provides a list of all modules with a \
summary for each. This page can also contain an overall description of the set of modules.
# 0: link to the Overview page
doclet.help.overview.packages.body=\
The {0} page is the front page of this API document and provides a list of all packages with a \
summary for each. This page can also contain an overall description of the set of packages.
doclet.help.package.intro=\
Each package has a page that contains a list of its classes and interfaces, with a summary for \
each. These pages may contain six categories:
each. These pages may contain the following categories:
doclet.help.module.intro=\
Each module has a page that contains a list of its packages, dependencies on other modules, \
and services, with a summary for each. These pages may contain three categories:
and services, with a summary for each. These pages may contain the following categories:
doclet.help.class_interface.head=\
Class or Interface
doclet.help.class_interface.intro=\
Each class, interface, nested class and nested interface has its own separate page. Each of \
these pages has three sections consisting of a class/interface description, summary tables, \
and detailed member descriptions:
Each class, interface, nested class and nested interface has its own separate page. \
Each of these pages has three sections consisting of a declaration and description, \
member summary tables, and detailed member descriptions. Entries in each of these \
sections are omitted if they are empty or not applicable.
doclet.help.class_interface.inheritance_diagram=\
Class Inheritance Diagram
doclet.help.class_interface.subclasses=\
@ -177,61 +194,89 @@ doclet.help.class_interface.declaration=\
Class or Interface Declaration
doclet.help.class_interface.description=\
Class or Interface Description
doclet.help.class_interface.summary=\
doclet.help.class_interface.member_order=\
The summary entries are alphabetical, while the detailed descriptions are in the order they \
appear in the source code. This preserves the logical groupings established by the programmer.
doclet.help.class_interface.note=\
Note:
doclet.help.class_interface.anno=\
Annotation interfaces have required and optional elements, but not methods.
doclet.help.class_interface.enum=\
Only enum classes have enum constants.
doclet.help.class_interface.record=\
The components of a record class are displayed as part of the declaration of the record class.
doclet.help.class_interface.property=\
Properties are a feature of JavaFX.
doclet.help.other_files.head=\
Other Files
doclet.help.other_files.body=\
Packages and modules may contain pages with additional information related to the \
declarations nearby.
doclet.help.use.head=\
Use
doclet.help.use.body=\
Each documented package, class and interface has its own Use page. This page describes what \
packages, classes, methods, constructors and fields use any part of the given class or \
package. Given a class or interface A, its "Use" page includes subclasses of A, fields declared \
package. Given a class or interface A, its Use page includes subclasses of A, fields declared \
as A, methods that return A, and methods and constructors with parameters of type A. \
You can access this page by first going to the package, class or interface, then clicking on \
the "Use" link in the navigation bar.
the USE link in the navigation bar.
doclet.help.tree.head=\
Tree (Class Hierarchy)
# 0: link to main Class Hierarchy page; 1: java.lang.Object
doclet.help.tree.intro=\
There is a {0} page for all packages, plus a hierarchy for each package. Each hierarchy page \
contains a list of classes and a list of interfaces. Classes are organized by inheritance \
structure starting with {1}. Interfaces do not inherit from {1}.
doclet.help.tree.overview=\
When viewing the Overview page, clicking on "Tree" displays the hierarchy for all packages.
When viewing the Overview page, clicking on TREE displays the hierarchy for all packages.
doclet.help.tree.package=\
When viewing a particular package, class or interface page, clicking on "Tree" displays the \
When viewing a particular package, class or interface page, clicking on TREE displays the \
hierarchy for only that package.
# 0: link to the Deprecated summary page
doclet.help.deprecated.body=\
The {0} page lists all of the API that have been deprecated. A deprecated API is not \
recommended for use, generally due to shortcomings, and a replacement API is usually given. \
Deprecated APIs may be removed in future implementations.
# 0: link to the Preview summary page
doclet.help.preview.body=\
The {0} page lists all of the Preview APIs. \
Preview APIs may be removed in future implementations.
doclet.help.index.head=\
Index
# 0: link to Index page; 1: list of links to pages
doclet.help.index.body=\
The {0} contains an alphabetic index of all classes, interfaces, constructors, methods, \
and fields, as well as lists of all packages and all classes.
and fields in the documentation, as well as summary pages such as {1}.
doclet.help.all_classes.head=\
All Classes
# 0: link to All Classes page
doclet.help.all_classes.body=\
The {0} page contains an alphabetic index of all classes and interfaces contained in the \
documentation, including annotation interfaces, enum classes, and record classes.
doclet.help.all_packages.head=\
All Packages
# 0: link to All Packages page
doclet.help.all_packages.body=\
The {0} page contains an alphabetic index of all packages contained in the documentation.
doclet.help.serial_form.body=\
Each serializable or externalizable class has a description of its serialization fields and \
methods. This information is of interest to those who implement rather than use the API. \
While there is no link in the navigation bar, you can get to this information by going to any \
serialized class and clicking "Serialized Form" in the "See Also" section of the class \
description.
# 0: link to Constant Values page
doclet.help.constants.body=\
The {0} page lists the static final fields and their values.
# 0: link to System Properties page
doclet.help.systemProperties.body=\
The {0} page lists references to system properties.
doclet.help.footnote=\
This help file applies to API documentation generated by the standard doclet.
doclet.help.enum.intro=\
Each enum has its own separate page with the following sections:
Each enum class has its own separate page with the following sections:
doclet.help.enum.class.intro=\
Each enum class has its own separate page with the following sections:
doclet.help.enum.declaration=\
Enum Declaration
doclet.help.enum.definition=\
Enum Description
doclet.help.annotation_type.intro=\
Each annotation type has its own separate page with the following sections:
doclet.help.annotation_interface.intro=\
@ -248,15 +293,15 @@ doclet.help.search.head=Search
# Introduction to Javadoc search features, followed by a list of examples
doclet.help.search.intro=You can search for definitions of modules, packages, types, fields, methods, \
system properties and other terms defined in the API, using some or all of the name, optionally \
using "camel-case" abbreviations. For example:
using "camelCase" abbreviations. For example:
# Used to list search examples, {0} is a search term and {1} the matching result
doclet.help.search.example={0} will match {1}
# {0} contains a link to the current Javadoc Search Specification
doclet.help.search.refer=Refer to {0} for a full description of search features.
doclet.help.search.refer=Refer to the {0} for a full description of search features.
# The URL for the Javadoc Search Specification. {0} will be replaced by the JDK version number
doclet.help.search.spec.url=https://docs.oracle.com/en/java/javase/{0}/docs/specs/javadoc/javadoc-search-spec.html
# The title for the Javadoc Search Specification
doclet.help.search.spec.title=the Javadoc Search Specification
doclet.help.search.spec.title=Javadoc Search Specification
doclet.ClassUse_Packages.that.use.0=Packages that use {0}
doclet.ClassUse_Uses.of.0.in.1=Uses of {0} in {1}

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

@ -112,7 +112,6 @@ doclet.Factory=Factory:
doclet.UnknownTag={0} is an unknown tag.
doclet.UnknownTagLowercase={0} is an unknown tag -- same as a known tag except for case.
doclet.noInheritedDoc=@inheritDoc used but {0} does not override or implement any method.
# doclet.malformed_html_link_tag=<a> tag is malformed:\n"{0}"
doclet.tag_misuse=Tag {0} cannot be used in {1} documentation. It can only be used in the following types of documentation: {2}.
doclet.Package_Summary=Package Summary
doclet.Requires_Summary=Requires

12
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css
View File

@ -675,6 +675,18 @@ section.description {
ul.help-section-list {
margin: 0;
}
ul.help-subtoc > li {
display: inline-block;
padding-right: 5px;
font-size: smaller;
}
ul.help-subtoc > li::before {
content: "\2022" ;
padding-right:2px;
}
span.help-note {
font-style: italic;
}
/*
* Indicator icon for external links.
*/

11
test/langtools/jdk/javadoc/doclet/testHelpFile/TestHelpFile.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2012, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2012, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -56,9 +56,8 @@ public class TestHelpFile extends JavadocTester {
// check a representative sample of the contents
checkOrder("help-doc.html",
"""
</div>
<section class="help-section">
<h2>Package</h2>""",
<section class="help-section" id="package">
<h3>Package</h3>""",
"""
<ul class="help-section-list">
<li>Interfaces</li>
@ -66,8 +65,8 @@ public class TestHelpFile extends JavadocTester {
<li>Enum Classes</li>""",
"""
</section>
<section class="help-section">
<h2>Class or Interface</h2>""",
<section class="help-section" id="class">
<h3>Class or Interface</h3>""",
"""
<ul class="help-section-list">
<li>Class Inheritance Diagram</li>

6
test/langtools/jdk/javadoc/doclet/testHelpOption/TestHelpOption.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2003, 2021, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@ -89,7 +89,7 @@ public class TestHelpOption extends JavadocTester {
"-nohelp",
testSrc("Sample.java"));
checkOutput("Sample.html", false, """
<li><a href="../help-doc.html">Help</a></li>""");
<li><a href="../help-doc.html#class">Help</a></li>""");
checkExit(Exit.OK);
}
@ -102,7 +102,7 @@ public class TestHelpOption extends JavadocTester {
checkExit(Exit.OK);
checkOutput("Sample.html", true,
"""
<li><a href="test-help.html">Help</a></li>""");
<li><a href="test-help.html#class">Help</a></li>""");
checkOutput("test-help.html", true,
"Help, help.");
}

7
test/langtools/jdk/javadoc/doclet/testHelpOption/test-help.html
View File

@ -4,6 +4,13 @@
</head>
<body bgcolor="white">
Help, help.
<p id="all-classes">All Classes</p>
<p id="all-packages">All Packages</p>
<p id="class">Class</p>
<p id="help">Help</p>
<p id="index">Index</p>
<p id="package">Package</p>
<p id="tree">Tree</p>
</body>
</html>

14
test/langtools/jdk/javadoc/doclet/testHtmlVersion/TestHtmlVersion.java
View File

@ -323,18 +323,18 @@ public class TestHtmlVersion extends JavadocTester {
<!-- ========= START OF TOP NAVBAR ======= -->""",
"""
<main role="main">
<div class="header">""",
<h1 class="title">JavaDoc Help</h1>""",
"""
<section class="help-section">
<h2>Overview</h2>
<section class="help-section" id="overview">
<h3>Overview</h3>
""",
"""
<section class="help-section">
<h2>Package</h2>
<section class="help-section" id="package">
<h3>Package</h3>
""",
"""
<section class="help-section">
<h2>Class or Interface</h2>
<section class="help-section" id="class">
<h3>Class or Interface</h3>
""",
"""
<footer role="contentinfo">""",

6
test/langtools/jdk/javadoc/doclet/testSingletonLists/TestSingletonLists.java
View File

@ -231,7 +231,11 @@ public class TestSingletonLists extends JavadocTester {
private int regionErrors;
private String fileName;
private boolean inheritanceClass;
private List<String> excludeFiles = List.of("overview-tree.html","package-tree.html","module-summary.html");
private List<String> excludeFiles = List.of(
"overview-tree.html",
"package-tree.html",
"module-summary.html",
"help-doc.html");
ListChecker(PrintStream out, Function<Path,String> fileReader) {
super(out, fileReader);