This document describes standard properties of the output generated
by the Standard Doclet for the javadoc tool in JDK 24.
Compatibility
The details given in the Structure section relate to aspects of interest to external consumers. This includes:
- the overall file hierarchy, in order to locate the specification of any given API element,
- the
idused to specify the position in a file of the specification of any given API element, in order to create a URL pointing at that element, and - any other details needed to locate the part of a page that is the primary specification for an API element, so that the part may be extracted for use by external tools.
Additional details may be added in future to accommodate new language features that do not fall within the scope of the existing details, and to describe other parts of the output, such as the serialized form and constant values pages.
The parts of a page that provide navigation and summary tables are not defined, and may be subject to change. The internal structure within the part of a page that is the primary specification for an API element is also not defined and may be subject to change.
The details given in the CSS Classes
section are provided for the benefit of users wanting to customize the
detailed appearance of their API documentation. It is currently subject
to change between releases, although efforts will be made to minimize
any changes to the classes of high level elements on each page, that may
be used to set the primary characteristics for the page, such as the
font and colors used on the page. It is recommended that users that just
want to customize the general appearance of their API documention should
just modify or override the CSS custom properties defined in the
:root section of the standard stylesheet provided by the
Standard Doclet.
Structure
The output generated by the Standard Doclet is organized into
directories and files, according to the kind of elements being
documented. Within HTML files, class attributes are used to
indicate the kind of element, and id attributes are used to
indicate specific elements.
For example, the java.base module contains the class
java.lang.String, which contains the isEmpty()
method. In the API documentation, the detailed documentation for this
method is in the file java.base/java/lang/String.html
(relative to the root directory of the generated documentation), and
within that file, the documentation for the method is in the section
whose start tag is
<section class="detail" id="isEmpty()>".
Modules
The files for the declaration of a module, and its contents, are all
placed in a top-level directory named after the module. The details of
the module declaration itself are placed in the file
module-summary.html in that directory.
For example, the details of a module named my.module
will be in the directory my.module, with the details of the
declaration itself in my.module/module-summary.html.
The documentation derived from the documentation comment in the
module's module-info.java file is in a section
element with id module-description.
Packages
The files for the declaration of a package, and its contents, are all placed in a directory named after the package, with a level of directory for each identifier in the name of the package. If the package is in the unnamed module, the directory hierarchy for the package will be in the top level directory for the documentation; if the package is in a named module, the directory hierarchy will be rooted in the module's directory.
The details of the package declaration itself are placed in the file
package-summary.html in directory for the package.
For example, the details of a package my.pkg that is
exported from module my.module will be in directory
my.module/my/pkg, with the details of the declaration
itself in my.module/my/pkg/package-summary.html.
The documentation derived from the documentation comment (if any) in
the package's package-info.java file is in a
section element with id
package-description.
Classes and Interfaces
The file for the declaration of a top-level class or interface is an HTML file named after the simple name of the class or interface. The file is in the directory for the enclosing package.
For example, the details of a class my.pkg.C that is
exported from module my.module will be in a file
my.module/my/pkg/C.html.
The file for the declaration of a nested class or interface is an HTML file named according the the simple name of the nested class or interface and its enclosing classes or interfaces. The file is in the directory for the enclosing package.
For example, the details of class my.pkg.C.Nested that
is exported from module my.module will be in a file
my.module/my/pkg/C.Nested.html.
The documentation derived from the documentation comment (if any) in
the class or interface's source file is in a section
element with id class-description.
Members
The details of the members of a class or interface are provided in the file for the immediately enclosing class or interface.
Except for the presence or otherwise of access modifiers, the access level of a member does not affect the structure of the presentation of that member.
Mandated members, such as default constructors and certain members of enum and record classes, are documented as if they were declared in the normal way with either an empty documentation comment or an appropriate generated documentation comment.
Fields
The documentation derived from the documentation comments (if any)
for the fields of a class or interface are grouped in a
section element with class field-details, with
the documentation for each field in a section element with
class detail and an id giving the name of the field.
Enum Constants
The documentation derived from the documentation comments (if any)
for the enum constants of an enum class are grouped in a
section element with class constant-details,
with the documentation for each constant in a section
element with class detail and an id giving the name of the
constant.
Constructors
The documentation derived from the documentation comments (if any)
for the constructors of a class are grouped in a section
element with class constructor-details, with the
documentation for each method in a section element with
class detail and an id giving the signature of the
constructor, consisting of the string <init>,
followed by a comma-separated list of the fully-qualified types of its
parameters, enclosed in parentheses. Note: in the HTML file, the
< and > characters are escaped as
< and >.
Methods
The documentation derived from the documentation comments (if any)
for the methods of a class or interface are grouped in a
section element with class method-details,
with the documentation for each method in a section element
with class detail and an id giving the signature of the
method, consisting of the name of the method, followed by a
comma-separated list of the fully-qualified types of its parameters,
enclosed in parentheses.
Annotation Interface Elements
The documentation derived from the documentation comments (if any)
for the elements of an annotation interface are grouped in a
section element with class member-details,
with the documentation for each element in a section
element with class detail and an id giving the name of the
element, followed by ().
Record Classes and Components
The documentation derived from the @param tags for the
record components is included in a section element with
class notes in the section for the main description of the
record class. Any fields and methods, either explicit or mandated, are
documented in the standard way.
CSS Classes
The following CSS classes are used by the Standard Doclet in order to associate style information provided in stylesheets with the different parts of the HTML pages.
Additional Details
The following constants are used for the additional information that may be provided for a declaration, such as whether it is deprecated or is a "preview" feature.
| Class | Description |
|---|---|
| deprecated-label | The class for the "Deprecated" label in a block describing the "deprecated" status of a declaration. |
| deprecation-block | The class for a block describing the "deprecated" status of a declaration. |
| deprecation-comment | The class for the details in a block describing the "deprecated" status of a declaration. |
| description-from-type-label | The class for a label indicating the element from which a description has been copied. |
| permits-note | The class for a note providing information about the permitted subtypes of a sealed class. |
| preview-block | The class for a block describing the "preview" status of a declaration. |
| preview-comment | The class for the details in a block describing the "preview" status of a declaration. |
| preview-label | The class for the "Preview" label in a block describing the "preview" status of a declaration. |
| tag-list | The class for a list containing the tags of an element. |
| tag-list-long | The class for a list containing the tags of an element when some tags have longer labels or contain commas. |
Details
The following constants are used for the details of the enclosed (program) elements of an enclosing element, such as a module, package or type declaration.
| Class | Description |
|---|---|
| details |
The class for the overall section element for all the
details about enclosed program elements.
|
| details-list | The class for the list of sublists containing the details for the different kinds of program elements. |
| detail |
The class for the section element containing the details
for a single enclosed element.
|
| member-list | The class for the list containing the details for the members of a given element kind. |
| constructor-details |
The class for the section containing the list of details
for all the constructors declared in a type element.
|
| constant-details |
The class for the section containing the list of details
for all the enum constants declared in a enum element.
|
| field-details |
The class for the section containing the list of details
for all the fields declared in a type element.
|
| member-details |
The class for the section containing the list of details
for all the members declared in a annotation type element.
|
| method-details |
The class for the section containing the list of details
for all the methods declared in a type element.
|
| property-details |
The class for the section containing the list of details
for all the properties declared in a JavaFX type element.
|
| serialized-class-details |
The class for a section element containing details of the
serialized form of an element, on the "Serialized Form" page.
|
Documentation Comments
The following constants are used for the components used to present the content generated from documentation comments.
| Class | Description |
|---|---|
| class-description | The class of the element used to present the documentation comment for a type element. The content of the block tags will be in a nested element with class notes. |
| module-description | The class of the element used to present the documentation comment for a module element, excluding block tags. |
| package-description | The class of the element used to present the documentation comment for package element. The content of the block tags will be in a nested element with class notes. |
| notes |
The class of the dl element used to present the block tags
in the documentation comment for a package, type or member element.
Additional (derived) information, such as implementation or inheritance
details, may also appear in this element.
|
Flex Layout
The following constants are used for the components of the top-level structures for "flex" layout.
| Class | Description |
|---|---|
| flex-box |
The class of the top-level div element used to arrange for
"flex" layout in a browser window. The element should contain two child
elements: one with class
flex-header and one with class
flex-content.
|
| flex-header |
The class of the header element within a
flex-box container. The element
is always displayed at the top of the viewport.
|
| flex-content |
The class of the div element within a
flex-box container This element
appears below the header and can be scrolled if too big for the
available height.
|
Header (Title Block)
The following constants are used for the main "header" ("heading")
that provides the title for the page. This should not be confused with
the header element that contains the top navigation
bar.
| Class | Description |
|---|---|
| header | The class for the element that contains all of the main heading for the page. |
| module-label-in-package | The class for the "module" label in the heading for a package declaration. |
| module-label-in-type | The class for the "module" label in the heading for a type declaration. |
| package-label-in-type | The class for the "package" label in the heading for a type declaration. |
| sub-title | The class for the element containing the label and name for the module or package that precedes the main title for the declaration of a package or type. |
| title | The class for the element containing the label and name for the main title on a page for the declaration of a package or type. |
Help Page
The following constants are used for the contents of the "Help" page.
| Class | Description |
|---|---|
| help-footnote | The class of the footnote at the bottom of the page. |
| help-note | The class of the "Note:" prefix. |
| help-section | The class of each subsection in the page. |
| help-section-list | The class of lists in a subsection in the page. |
| help-toc" | The class of the top level list for the table of contents for the page. |
| help-subtoc" | The class of the second-level lists in the table of contents for the page. |
Miscellaneous
The following constants are used in various places across a variety of pages.
| Class | Description |
|---|---|
| block |
The class of a div element containing part of a
documentation comment.
|
| block-list |
The class of a ul element containing parts of documentation
comments.
|
| circle |
The class of a ul element in the hierarchical tree view.
|
| class-uses |
The class of a ul element listing classes in the uses page.
|
| copy |
The class for a button element to copy some page content to
the clipboard.
|
| external-link |
The class of an a element for a link with an external
target.
|
| hierarchy |
The class of a section element containing a hierarchical
tree view.
|
| horizontal |
The class of a ul element with horizontal (inline) display
style.
|
| implementation-label |
The class of a span element containing implementation
details of a "provides" entry in a module page.
|
| index |
The class of a dl element in the body of index pages.
|
| inheritance |
The class of a div element containing the inheritance tree
of a class page.
|
| inherited-list |
The class of a div element containing a summary of
inherited members in the class page.
|
| invalid-tag | The class of an element that acts as a notification for an invalid tag or other invalid items. |
| legal-copy |
The class of a p element containing legal copy in the page
footer.
|
| member-name-link |
The class of an a element for a link in member summary
lists.
|
| name-value |
The class of a dl element containing serial UID information
in the serialized form page.
|
| packages |
The class of a section element containing the packages
section in the constant field values page.
|
| package-hierarchy-label |
The class of a span element containing the package
hierarchy label in the tree page.
|
| package-uses |
The class of a li element containing a content section of
the package uses page.
|
| ref-list | The class for the list of references to an external specification. |
| serialized-package-container |
The class of a section element for a package in the
serialized form page.
|
| source-container |
The class of a div element containing source code in the
source page.
|
| source-line-no |
The class of a span element containing a line number in the
source page.
|
| type-name-link |
The class of an a element for a link to a class or
interface.
|
Navigation Bar
The following constants are used for the main navigation bar that
appears in the header and footer elements on
each page.
| Class | Description |
|---|---|
The class for the overall div element containing the
header element for the page.
|
|
| about-language |
The class for the element containing the information (such as the
product name and version) provided by the -header or
-footer command line option.
|
| The class for the highlighted item in the list of navigation links, indicating the current page. | |
| The class for the navigation bar toggle button for smaller displays. | |
| The class for the primary list of navigation links. | |
The class for the div element containing the "Search"
control.
|
|
The class for a div element containing a link to skip the
navigation header. The element is typically invisible, but may be used
when navigating the page with a screen reader.
|
|
The class for a div element containing a list of subsidiary
navigation links.
|
|
| The class for the list of subsidiary navigation links. | |
| The class for the list of subsidiary navigation links for smaller displays. |
Page Styles For
<body> Elements
The following constants are used for the class of the
<body> element for the corresponding pages.
| Class | Description |
|---|---|
| all-classes-index-page |
The class of the body element for the "All Classes" index
page.
|
| all-packages-index-page |
The class of the body element for the "All Packages" index
page.
|
| class-declaration-page |
The class of the body element for a class-declaration page.
|
| class-use-page |
The class of the body element for a class-use page.
|
| constants-summary-page |
The class of the body element for the constants-summary
page.
|
| deprecated-list-page |
The class of the body element for the page listing any
deprecated items.
|
| deprecated-in-release-page |
The class of the body element for the page listing any
deprecated items.
|
| doc-file-page |
The class of the body element for a "doc-file" page..
|
| external-specs-page |
The class of the body element for the "external
specifications" page.
|
| help-page |
The class of the body element for the "help" page.
|
| index-page |
The class of the body element for a page in either the
"single" or "split index".
|
| index-redirect-page |
The class of the body element for the top-level redirect
page.
|
| module-declaration-page |
The class of the body element for a module-declaration
page.
|
| module-index-page |
The class of the body element for the module-index page.
|
| new-api-list-page |
The class of the body element for the page listing new API
elements.
|
| package-declaration-page |
The class of the body element for a package-declaration
page.
|
| package-index-page |
The class of the body element for the package-index page.
|
| package-tree-page |
The class of the body element for the page for the package
hierarchy.
|
| package-use-page |
The class of the body element for a package-use page.
|
| preview-list-page |
The class of the body element for the page listing any
preview items.
|
| search-page |
The class of the body element for the search page.
|
| serialized-form-page |
The class of the body element for the serialized-forms
page.
|
| source-page |
The class of the body element for a page with the source
code for a class.
|
| system-properties-page |
The class of the body element for the system-properties
page.
|
| tree-page |
The class of the body element for the page for the class
hierarchy.
|
Search Index And Results
The following constants are used for items in the static and interactive search indexes.
| Class | Description |
|---|---|
| page-search-details |
The class for a details element in the search page to show
additional information.
|
| page-search-info |
The class for a div element in the search page which
contains additional information.
|
| search-tag-link |
The class for a link in the static "Index" pages to a custom searchable
item, such as defined with an @index tag.
|
| search-tag-result |
The class for a custom searchable item, such as defined with an
@index
tag.
|
| vertical-separator | The class for the separator in the list of pages given at the top of the static "Index" page(s). |
Signatures
The following constants are used for the components of a signature of an element
| Class | Description |
|---|---|
| module-signature | The class of an element containing a module signature. |
| package-signature | The class of an element containing a package signature. |
| type-name-label |
The class of a span element containing the type name in a
type signature.
|
| type-signature | The class of an element containing a type signature. |
| member-signature | The class of an element containing a member signature. The signature will contain a member name and, depending on the kind of element, any of the following: annotations, type parameters, modifiers, return type, parameters, and exceptions. |
| annotations |
The class of a span element containing any annotations in
the signature of an element.
|
| exceptions |
The class of a span element containing any exceptions in a
signature of an executable element.
|
| extends-implements |
The class of a span element containing the
extends or implements section in a signature
of a type element.
|
| element-name |
The class of a span containing the element name in the
element's signature.
|
| modifiers |
The class of a span containing any modifiers in the
signature of an element.
|
| parameters |
The class of a span containing any parameters in the
signature of an executable element.
|
| permits |
The class of a span containing the permits
section of a sealed class element.
|
| return-type |
The class of a span containing the return type in the
signature of a method element.
|
| type-parameters |
The class of a span containing type parameters in the
signature of an element, used when the type parameters should reasonably
be displayed inline.
|
| type-parameters-long |
The class of a span containing type parameters in the
signature of an element, used when the type parameters are too long to
be displayed inline. Implementation Note: The threshold for
choosing between type-parameters and
type-parameters-long is 50 characters.
|
Snippets
The following constants are used for the contents of snippets. In
addition, the translation of a snippet may use the class
language-LANG where LANG is either specified explicitly by
the "lang" attribute in a snippet tag, or can be inferred from the kind
of an external snippet.
| Class | Description |
|---|---|
| snippet |
The class of the pre element presenting a snippet.
|
| snippet-container |
The class of the div element containing a snippet element.
|
| snippet-copy | The class of the UI element to copy snippet content to the clipboard. |
| bold |
The class of text highlighted with the type bold.
|
| italic |
The class of text highlighted with the type italic.
|
| highlighted |
The class of text highlighted with the type highlighted.
|
Summaries
The following constants are used for the HTML elements that provide summary information, either of the program elements enclosed by some program element, or in pages providing aggregate information about similar program elements. As a general rule, summaries are typically displayed as tables, with rows containing the name or signature of an element, and the first sentence of the description of that element. The name or signature is typically linked to a corresponding "Details" section.
Note: the "Summary" information on a module declaration page for "Services" would be better characterized as "Details" information, since it contains the full text of the descriptions in the @provides and @uses tags, and not just the first sentence.
| Class | Description |
|---|---|
| summary |
The class for the overall section element containing all
the different kinds of summary for the parts of the program element
declared on this page.
|
| summary-list |
The class for the list element of all the different kinds
of summary for the parts of the program element declared on this page.
|
| constructor-summary |
The class for the section element containing a summary of
the constructors for a type.
|
| field-summary |
The class for a section element containing a summary of the
fields of a type.
|
| member-summary |
The class for a section element containing the members of a
given kind for a type.
|
| method-summary |
The class for the section element containing a summary of
the methods of a type.
|
| modules-summary |
The class for the section element containing a summary of
the module dependencies of a module.
|
| nested-class-summary |
The class for the section element containing a summary of
the nested classes of a type.
|
| packages-summary |
The class for the section element containing a summary of
the packages provided by a module, and the class for the list of
packages on the "All Packages" index page.
|
| property-summary |
The class for the section element containing a summary of
the properties for a type.
|
| services-summary |
The class for the section element containing a summary of
the services provided or used by a module.
|
| constants-summary |
The class for a section element on the "Constants Field
Values" page, and the class for the section element
for the enum constants of an enum class.
|
| contents-list |
The class for a ul element in various summary pages
containing links to the contents of the page.
|
| preview-feature-list |
The class for a ul element in the preview summary page
containing information about the preview features in the current
release.
|
Tables
The following constants are used for "summary" and "details" tables. Most tables are summary tables, meaning that, in part, they provide links to details elsewhere. A module page has details tables containing the details of the directives.
| Class | Description |
|---|---|
| two-column-summary |
The class of a div element whose content should be rendered
as a table with two columns.
|
| three-column-summary |
The class of a div element whose content should be rendered
as a table with three columns.
|
| three-column-release-summary |
The class of a div element whose content should be rendered
as a table with three columns where the middle column requires less
space as it only contains a release name.
|
| four-column-summary |
The class of a div element whose content should be rendered
as a table with four columns.
|
| details-table |
The class of a div element used to present details of a
program element.
|
| summary-table |
The class of a div element used to present a summary of the
enclosed elements of a program element. A summary-table
typically references items in a corresponding
details-list.
|
| active-table-tab | The class of the "tab" that indicates the currently displayed contents of a table. This is used when the table provides filtered views. |
| caption | The class for the caption of a table. The caption is displayed as a single inactive tab above the table. |
| checkboxes |
The class for a div element containing a row of checkboxes
to select items to view in summary tables.
|
| table-header | The class of an element that is part of a table header. |
| table-tab | The class of a "tab" that indicates an alternate view of the contents of a table. This is used when the table provides filtered views. |
| table-tabs |
The class of the div element that contains the tabs used to
select the contents of the associated table to be displayed.
|
| col-constructor-name | The class of the cells in a table column used to display the name of a constructor. |
| col-first | The class of the first column of cells in a table. This is typically the "type and modifiers" column, where the type is the type of a field or the return type of a method. |
| col-last | The class of the last column of cells in a table. This is typically the "description" column, where the description is the first sentence of the elements documentation comment. |
| col-summary-item-name | The class of the cells in a table column used to display the name of a summary item. |
| col-plain | The class of the cells in a table column used to display additional information without any particular style. |
| col-second | The class of the second column of cells in a table. This is typically the column that defines the name of a field or the name and parameters of a method. |
| even-row-color | A class used to provide the background for the rows of a table, to provide a "striped" effect. This class and odd-row-color are used on alternating rows. The classes are applied dynamically when table "tabs" are used to filter the set of rows to be displayed |
| odd-row-color | A class used to provide the background for the rows of a table, to provide a "striped" effect. This class and even-row-color are used on alternating rows. The classes are applied dynamically when table "tabs" are used to filter the set of rows to be displayed |