JEP 221: New Doclet API

AuthorJonathan Gibbons
OwnerKumar Srinivasan
Created2014/05/09 01:45
Updated2017/06/02 20:35
TypeFeature
StatusClosed / Delivered
Componenttools / javadoc(tool)
ScopeJDK
Discussionjavadoc dash dev at openjdk dot java dot net
EffortM
DurationM
Priority3
Reviewed byAlex Buckley, Brian Goetz, Jonathan Gibbons
Endorsed byBrian Goetz
Release9
Issue8042809

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

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.

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.