JEP 221: Simplified Doclet API

AuthorJonathan Gibbons
OwnerKumar Srinivasan
Created2014/05/09 01:45
Updated2017/05/25 21:39
Componenttools / javadoc(tool)
Discussionjavadoc dash dev at openjdk dot java dot net
Reviewed byBrian Goetz, Jonathan Gibbons
Endorsed byBrian Goetz


Replace the Doclet API with a simpler design that leverages newer alternative APIs with improved functionality, and update the standard doclet to use it.



Although improving performance is not a goal, it is expected that the performance of the javadoc tool and the standard doclet will be improved as a result of this work.


The current APIs have the following issues that need to be addressed.


The new Doclet API uses the Language Model API and Source Tree API.

The javadoc tool is updated to recognize doclets written against the new API. The old APIs will be supported for transitional purposes, and will be frozen, that is, not updated to support any new language features introduced during the transition period.

The standard doclet is updated in accordance with the new API, and the majority of the work for this project, an exercise in translating between the old idioms and the new ones.

The standard doclet supports a secondary plugin API known as the Taglet API. Taglets provide the ability for users to define custom tags that can be used in Javadoc comments, and to specify how such tags should appear within the generated documentation. For historical reasons, there were two versions of the Taglet API, one public and one internal. The public version has been modified to use the Language Model and Source Tree APIs.

It is known that there are some existing user-written doclets that directly reference code in the old "standard doclet", even though that code is not (and never has been) a supported interface. Since that code is difficult to maintain and update, especially with respect to recent new language features, it will be deprecated in JDK 9, and withdrawn in a future release. Until then, users will be encouraged to update their doclets to use the new API.

In addition, the existing Doclet API, which is currently a supported API, will in time be deprecated and eventually withdrawn.


A few tests were developed for newer use-cases.