JEP 221: New Doclet API

Summary

Provide a replacement for the Doclet API to leverage appropriate Java SE and JDK APIs, and update the standard doclet to use the new API.

Note

In this document, the term "old Doclet API" refers to the APIs in com.sun.javadoc and the "old standard doclet" refers to com.sun.tools.doclets.standard.Standard.

The term "new Doclet API" refers to the APIs in jdk.javadoc.doclet, and the "new standard doclet" refers to jdk.javadoc.doclet.StandardDoclet.

Goals

• 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 documentation comments in favor of the Compiler Tree API, com.sun.source.doctree, introduced in JDK 8.

• Replace the use of the "template class" com.sun.javadoc.Doclet with a suitable new interface type.

Non-Goals

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

Motivation

The old Doclet 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 modeled 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, inefficient and incompletely-specified support for analyzing the contents of a documentation 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 support for analyzing comments is backed by a poor and inefficient implementation, in the old standard doclet, which relies heavily on using substring matching to separate the constructs within the comment.

Description

The new Doclet API is declared in the jdk.javadoc.doclet package. It uses the Language Model API and the Compiler Tree API.

The javadoc tool is updated to recognize doclets written against the new Doclet API. The old Doclet 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 existing standard doclet supports a secondary plug-in API known as the Taglet API. Taglets provide the ability for users to define custom tags that can be used in documentation comments, and to specify how such tags should appear within the generated documentation. The updated standard doclet supports an updated taglet API.

Risks and Assumptions

In addition, the old Doclet API, which is currently a supported API, has been deprecated and may be removed in a future release. Users of the old Doclet API are encouraged to migrate their code to use the new Doclet API.

It is known that there are some existing user-written doclets that directly reference code within 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, the old "standard doclet" has been deprecated for removal in JDK 9, and will be removed in a future release.

Testing

The existing set of tests for the Doclet API and standard doclet have been adapted to test the new API and the new standard doclet. Additional tests have been added to cover edge cases.