JEP 221: Simplified Doclet API
|Component||tools / javadoc(tool)|
|Discussion||javadoc dash dev at openjdk dot java dot net|
|Reviewed by||Brian Goetz, Jonathan Gibbons|
|Endorsed by||Brian 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.
Reduce the maintenance burden of outdated APIs.
Eliminate the use of a custom language-model API in favor of the standard language-model API,
javax.lang.model, introduced in Java SE 6.
Eliminate the simplistic support for analyzing Javadoc comments in favor of the DocTree API,
com.sun.source.doctree, introduced in JDK 8.
Replace the use of the "template class"
com.sun.javadoc.Docletwith a suitable new interface type.
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 API specifies that a doclet is simply a class that implements some or all of a set of static methods, as exemplified by the template class
com.sun.javadoc.Doclet. The use of static methods is particularly troublesome because they require the use of static members to share data between the methods. This has negative implications for both concurrent usage and for testing.
The API provides its own language-model API, which has a number of limitations (for example, arrays are not modelled well) and which is a burden to update as the Java language evolves in ways that affect API signatures (for example, generics, type annotations, and default methods.)
The API provides minimal and incompletely-specified support for analyzing the contents of a Javadoc comment. This places a significant burden on any doclet looking to process the contents of a comment. The API also provides no support for determining the position within the containing source file of constructs within the comment. This makes it effectively impossible to provide accurate position information for any diagnostics that should be reported.
The poor API support for analyzing comments is backed by a poor and inefficient implementation, which relies heavily on using substring matching to separate the constructs within the comment.
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.
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.
Tests will need to be developed for newer use-cases.