JEP 221: Simplified Doclet API

AuthorJonathan Gibbons
OwnerKumar Srinivasan
Created2014/05/09 01:45
Updated2016/06/08 22:25
TypeFeature
StatusCompleted
Componenttools / javadoc(tool)
ScopeJDK
Discussionjavadoc dash dev at openjdk dot java dot net
EffortM
DurationM
Priority3
Reviewed byBrian Goetz, Jonathan Gibbons
Endorsed byBrian Goetz
Release9
Issue8042809

Summary

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

Goals

Non-Goals

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.

Motivation

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

Description

Reformulate the Doclet API to use the Language Model API and DocTree API. What remains will be an "umbrella API" to leverage those other APIs.

The javadoc tool will need to be updated to recognize doclets written against the new API. We may wish to support the existing API during a transition period, but it is likely we would freeze the old API and not update it with support for any new language features introduced during the transition period.

The standard doclet will have to be updated in accordance with the new API, and this will be majority of the work for this project. For the most part, this will be 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 are already two versions of the Taglet API, one public and one internal. The public version uses existing API that would be made obsolete by other parts of this proposal; therefore this API will have to be updated accordingly.

It is known that there are some existing user-written doclets that directly reference code in the current "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.

Testing

Tests will need to be developed for newer use-cases.