Summary
-------

Provide a replacement for the [Doclet API][doclet] 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][model], `javax.lang.model`, introduced
    in Java SE 6.

  - Eliminate the simplistic support for analyzing documentation comments in
    favor of the [Compiler Tree API][compilertree], `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][taglet].  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.

[doclet]: http://docs.oracle.com/javase/8/docs/jdk/api/javadoc/doclet/index.html
[compilertree]: http://docs.oracle.com/javase/8/docs/jdk/api/javac/tree/com/sun/source/doctree/package-summary.html
[model]: http://docs.oracle.com/javase/8/docs/api/javax/lang/model/package-summary.html
[taglet]: http://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/taglet/overview.html