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.

The Main javadoc Software Stack
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).



Builders use the abstract Writer API to cause output to be generated.


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 ( and its predecessor (com.sun.mirror), the Doclet API was used as a simple, better-than-nothing modelling API.

Doclet API


The Doclet API (jdk.javadoc.doclet) is a plugin-API to process elements and their doc comments in Java source code and classes.

This API supersedes an older version of the Doclet API, in com.sun.javadoc.

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.

External API

The following table shows the external API used by javadoc.

External API used by javadoc
API Packages Status Usage
Compiler API* 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.

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** 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.

Internal components of javadoc
Component Subcomponent Package API used Notes

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
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
Compiler Tree API
Compiler API

Support for accessing DocTree, DocLint, etc
Support for writing HTML output jdk.javadoc.internal.doclets.formats.html

Language Model API
Compiler Tree API
Compiler API

Classes to general HTML pages

Package Map

The following table lists the primary packages within javadoc.

Package map
Package Component Subcomponent Notes



Tool/Doclet interface Doclet API


Taglet API



Tool API entry


Main tool


Resource files for tool




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.









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 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


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