javadoc Architecture
javadoc is a JDK tool, that can read Java source code containing documentation comments, and which can generate output based on the declarations in the source code and the corresponding documentation comments.
The tool can be invoked from the command line or via an API.
It has a plug-in architecture, such that it can be configured to generate different kinds of output, by means of plug-ins called doclets. When using the tool, a user can specify to use a doclet they provide, or use the standard doclet provided with the tool itself.
The standard doclet supports a syntax for documentation comments
that includes a subset of HTML markup, and so-called
"javadoc tags", such as @param,
@return, @author,
{@code...}, etc. Although the use of this syntax is
widespread, it is not required for all doclets to support it: other
doclets may choose to support different syntax rules, for a
different style of markup, such as markdown. The standard doclet
generates HTML output, but other doclets may generate
other forms of output, such as XML, PDF, and so on.
The standard doclet supports a subsidiary plug-in mechanism for user-defined javadoc tags, called taglets.
This note discusses the internal organization of the overall javadoc tool and the external API on which it depends.
The Main javadoc Software Stack
The following table shows the overall software stack for javadoc and for doclets like the standard doclet.
| Component | Notes | ||
|---|---|---|---|
|
other doclets |
other writers |
HTMLDocletWriter and subtypes
|
In theory, there may be many different writers, although we only support one: the HTML Writer. In times past, there was a writer that could generate FrameMaker documents via MML (Maker Markup Language) and MIF (Maker Interchange Format). |
|
Writers
|
Builders use the abstract Writer API to cause output to be generated. | ||
|
Builders
|
Builders model the semantic content of a page of documentation, without regard to the output format (such as the summary table of declarations, followed by the detailed list) | ||
|
Standard Doclet
|
In theory, there may be many different doclets, although we only support one ... the standard doclet, that generates HTML documentation based on the doc comments. The standard doclet is just a simple wrapper around the (internal) HtmlDoclet. In times past, before the advent of the Language Model API (javax.tools) and its predecessor (com.sun.mirror), the Doclet API was used as a simple, better-than-nothing modelling API. |
||
|
Doclet API
|
The Doclet API ( This API supersedes an older version of the Doclet API,
in |
||
| javadoc tool | The main javadoc tool. It uses the javac front end to parse and analyze source and class files to be documented, and then invokes a nominated doclet to process the elements and their documentation comments. | ||
| javac | |||
External API
The following table shows the external API used by javadoc.
| API | Packages | Status | Usage |
|---|---|---|---|
| Compiler API | javax.tools.* |
Java SE | The javadoc tool provides an implementation of the DocumentationTool interface for use by ToolProvider.getSystemDocumentationTool. |
| Language Model API | javax.lang.model.* |
Java SE | A doclet can examine the declarations to be documented using the Language Model API. The API provides access to the "mostly raw" text of a documentation comment. |
| Compiler Tree API |
|
JDK | A doclet may use classes in these packages to parse documentation comments into simple AST, according to the syntax rules used by the standard doclet. Parsing a doc comment will always succeed, although the tree may contain nodes that represent bad input. |
| DocLint |
|
internal | A doclet may use classes in these packages to check doc comment
ASTs (generated by com.sun.source.* API) for
questionable or incorrect input. |
| javac internal API | com.sun.tools.javac.** |
internal | The javadoc tool uses a modified javac front end to read source and class files. The modifications are generally done by using custom subtypes of javac components, to override the standard javac behavior. |
Internal components
The following table shows the internal components within javadoc.
| Component | Subcomponent | Package | API used | Notes |
|---|---|---|---|---|
| Tool |
Main tool | jdk.javadoc.internal.tool |
javac internal API Language Model API |
Main command-line entry point, top level driver etc |
| API entry | jdk.javadoc.internal.api |
Compiler API | Implementation of
javax.tools.DocumentationTool |
|
| Custom javac components | jdk.javadoc.internal.tool |
javac internal API | Subtypes of javac internal components | |
| Tool/Doclet interface | Doclet API | jdk.javadoc.doclet |
Language Model API | API and SPI for a doclet to interact with the enclosing tool |
| Taglet API | jdk.javadoc.doclet.taglet |
Compiler Tree API | API and SPI for a taglet to interact with the enclosing doclet | |
| Doclet | Shared support for standard javadoc tags | jdk.javadoc.internal.doclets.toolkit |
Language Model API |
Support for accessing DocTree, DocLint, etc |
| Support for writing HTML output | jdk.javadoc.internal.doclets.formats.html |
Language Model API |
Classes to general HTML pages |
Package Map
The following table lists the primary packages within javadoc.
| Package | Component | Subcomponent | Notes |
|---|---|---|---|
|
|
|||
|
|
Tool/Doclet interface | Doclet API | |
|
|
Taglet API | ||
|
|
|||
|
|
Tool | API entry | |
|
|
Main tool | ||
|
|
Resource files for tool | ||
|
|
Doclet | ||
|
|
Wrapper class for HTML Doclet | ||
|
|
|||
|
|
Format-independent support for standard tags | ||
|
|
Format-independent resources for standard generators |
||
|
|
|||
|
|
|||
|
|
|||
|
|
(container for different output generators) | ||
|
|
HTML output generation | ||
|
|
Basic support for HTML trees |
||
|
|
Resource files for HTML output generator |
||
|
|
Scripts and related files for inclusion in generated output. | ||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
|||
|
|
Workarounds
During the development of the new doclet API, some problems have been uncovered in the various APIs used by javadoc, which cannot trivially be worked around. Addressing these issues requires further investigation and may require changes to those APIs.
| Issue | Bug | Description |
|---|---|---|
| doclet needs to be able to throw an exception |
A doclet needs to be able to throw an exception from Doclet.run to signal that it cannot complete the task. Solution: add DocletException, thrown from run. |
|
| doclet needs a DocTreeMaker | JDK-8146208 |
Although most doctree nodes are created in the Compiler Tree API by parsing doc comments, a doclet may need to synthesize additional trees, such as comments for mandated methods (like the values and value of methods for an enum, or for JavaFX properties.) The current DocTreeMaker is internal to the Compiler Tree API and uses internal types. Solution: add a public DocTreeMaker to the Compiler Tree API Status: In progress: JDK-8146208 |
| doclet needs access to doclint |
The format of a doc comment depends on the doclets that will be use to process it. Not all doclets use the standard javadoc tags and/or HTML markup. Therefore the need and ability to use doclint is a characteristic of the doclet being used, and not the javadoc tool. Furthermore, doclint is a JDK-only feature, and not available via any public or supported API. Solution: ideally, it needs to be possible to create an instance of the doclint tool from an instance of the standard doclet, using only the information available to the doclet. |
|
| doclet needs a cache of Element→TreePath |
The current implementation of the method to get a TreePath for a element is slow enough that it needs to be cached. The information is generally created by the javadoc tool, but needs to be used by the doclet as well. Solution: long term we should look at speeding up the getTreePath method in (Doc)Trees, and possibly caching the results there, so that a downstream client cache is unnecessary |
|
| SerializedForm |
The old ClassDoc class provided direct support for details about the serialization details of a class. There is no direct analog on TypeElement. Solution: long term, we should be able to infer all the necessary details through the Language Model API. |
|
| issues with javax.lang.model |
There may be some issues with some of the methods on the Language Model API, with missing or inconvenient functionality. Solution: long term we should work to address these API issues |
Recent History
Much of the work over the past few releases has been to improve internal abstractions as a way to improve performance and reduce errors. Also, more formal specifications are being created and used to help document the intended behavior.
| Date | Item | Description |
|---|---|---|
| JDK 13 | Search | Improved Search |
| Specification | “Javadoc Search Specification” | |
| JDK 11 | Navigation | New abstraction for building the navigation header for generated pages. still needs improvement. |
| VisibleMemberTable | Replace VisibleMemberMap with improved abstraction | |
| JDK 10 | Head, Links, Table | New abstractions for building HTML fragments |
| JDK 9 | New Doclet | New doclet, based on javax.lang.model API |
| Resources, Contents, Messages | Improved abstractions for managing/caching resource-based items | |
| Specification | “Document Comment Specification for the Standard Doclet” | |
| JDK 8 | DocPath, DocFile | Introduce abstractions to replace use of Strings to model paths within the generated documention |
| JDK 7 | HtmlTree, HtmlTag, HtmlAttr, etc | Introduce HtmlTree to replace use of println to generate HTML |
