Internally, javadoc is composed of two primary parts:
the tool, and a series of
doclets.
The tool provides a common infrastructure for command-line processing, and for reading the declarations and documentation comments in Java source files, while doclets provide a user-selectable backend for determining how to process the declarations and their documentation comments.
The following provides a top-down description of the overall javadoc software stack.
The jdk. is a thin public wrapper
around the internal HTML doclet.
The jdk. class
and other classes in the
formats. package
customize the abstract pages generated by the toolkit layer to generate
HTML pages. Some pages are specific to the HTML output format,
and do not have an abstract builder in the toolkit layer.
Individual pages of output are generated by page-specific subtypes of
jdk..
The jdk. class
provides configuration information that is relevant to all the generated pages.
The class extends the jdk.
class provided by the toolkit layer.
The classes in the formats.html package use an internal
library in the
formats. package,
to create trees (or acyclic graphs) of
HTML tree nodes.
Apart from using a common format-neutral supertype,
jdk., the markup library
is mostly independent of the rest of the javadoc software stack.
The jdk. provides
configuration information that is relevant to all the generated pages.
Some of the information is provided by abstract methods which are implemented
in format-specific subtypes of the class.
The toolkit layer also provides utility classes used by this layer and by format-specific layers.
Generally, it is intended that doclets should use the
Language Model API to navigate the structure of a Java program,
without needing to access any internal details of the underlying javac implementation.
However, there are still some shortcomings of the Language Model API,
and so it is still necessary to provide limited access to some of those internal details.
Although not enforceable by the module system, by design the access to javac
internal details by doclets based on AbstractDoclet is restricted to the aptly-named
jdk. class.
Doclets are obviously not required to use
jdk. and other classes in
the toolkit layer. In times past, it was common to write doclets to analyze
code using the then-current API as an early version of a Java language model.
That old API has been replaced by the Language Model API,
and tools that wish to use that API to analyze Java programs have a choice of
how to invoke it, using the javac support for
annotation processing,
or plugins, as well as doclets.
Which is best for any application will depend of the circumstances, but
if a tool does not need access to the documentation comments in a program,
it is possible that one of the other invocation mechanisms will be more convenient.
The Doclet API is the interface layer between the javadoc tool and the code to process the elements specified to the tool.
Above this layer, in any doclet, the code is expected to use the Language Model API to navigate around the specified elements, and/or the DocTree API to examine the corresponding documentation comments.
After reading the command-line options, the tool uses a modified javac
front end to read the necessary files and thus instantiate the
elements to be made available to
the doclet that will be used to process them.
The tool uses an internal feature of the javac architecture, which
allows various components to be replaced by subtypes with modified behavior.
This is done by pre-registering the desired components in the javac
Context.
The tool uses this mechanism to do the following:
package.html
files in any package directories that are read; and
This is NOT part of any supported API. If you write code that depends on this, you do so at your own risk. This code and its internal interfaces are subject to change or deletion without notice.
| Modifier and Type | Class and Description |
|---|---|
| public class |