Skip to content
Permalink
Browse files
8263198: javadoc HELP page
Reviewed-by: hannesw
  • Loading branch information
jonathan-gibbons committed Mar 24, 2021
1 parent 5ca5962 commit 3e751a5a9c3ee9d26643e4243ef35ff9e7af14c2
Show file tree
Hide file tree
Showing 14 changed files with 408 additions and 145 deletions.
@@ -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");
@@ -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.
*/

Large diffs are not rendered by default.

@@ -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,11 +445,29 @@ public static HtmlId forTabPanel(HtmlId tableId) {
}


/**
* 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();
case PACKAGE -> forPackage((PackageElement) el).name();
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("_", "-"));
}
}
@@ -387,6 +387,7 @@ private void addSummaryLinks(Content tree) {
addListToNav(listContents, tree);
}
break;

case MODULE:
if (displaySummaryModuleDescLink) {
addContentToList(listContents,
@@ -419,6 +420,18 @@ private void addSummaryLinks(Content tree) {
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 @@ private void addDetailLinks(Content tree) {
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 @@ private void addHelpLink(Content tree) {
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, "")));
}
}
@@ -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;
@@ -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}

0 comments on commit 3e751a5

Please sign in to comment.