Draft JEP: Javadoc Standard Doclet Simplification

[Kumar Srinivasan]

Hello,

Here is a preview of the JEP, that will be submitted formally, please 
let us know
if you have any comments.

Thanks
Kumar

-------------- next part --------------
Title: Javadoc Standard Doclet Simplification
Author: Kumar Srinivasan
Organization: Oracle Corp.
Date: 2014/03/02
State: Draft
Exposure: Open
Type: Feature
Component: tools/javadoc
Scope: JDK
JSR:
RFE: 8035473
Internal-refs:
Discussion: javadoc-dev at openjdk.java.net
Start: 2014/Q1
Depends: 
Blocks:
Effort: M
Duration: M 
Reviewed-by: Jonathan Gibbons 
Endorsed-by: 
Funded-by:

Summary
-------
Simplify the standard Doclet by migrating from the legacy Standard Doclet API to a more modern API built on javax.lang.model and DocTrees, improving both the usability of the API and the maintainability of the implementation.

Goals
-----
Improve the APIs and implementation for JavaDoc generation, leading to better diagnostics, performance, and new capabilities such as auto-correction of HTML, possibly deprecating the old API in JDK9 and complete removal in JDK10.

Motivation
----------

The current JavaDoc APIs located in the package com.sun.javadoc are publicly exported APIs, the API specification and the implementation is outdated and inefficient, for the following reasons:

    a. Poor reusability: the current APIs are not good abstract
       implementations for Doclet and Tag. The standard doclet 
       is not designed for extension, for example it is hard to
       express array dimensions.

    b. Outdated API idioms: these APIs use arrays rather than
       Collections, often requiring conversions on both sides of
       the APIs.

    c. Inefficient implementation: the current implementation
       produces far more memory churn than necessary, because of
       its use of String and String.substring().

    d. Poor diagnostic support: inaccurate source positions,
       resulting in poor diagnostics information.

Description
-----------

Reformulate the Doclet API to use the javax.lang.model and the Taglet API to use doctree, and upgrade these to use more modern design practices. Thus javadoc will be completely decoupled completely from the javac compiler, and will be limited to using the standard APIs, this will allow the javadoc APIs to be extended in the future to implement newer tools.

Investigate and implement the following items:

1. Re-implement the standard doclet as a Service Provider 
   using the Service Provider Interface (SPI).

2. Re-implement the Doclet API using javax.lang.model, thereby
   several redundant APIs and its classes can be eliminated and 
   the underlying implementation simplified. Manipulating 
   Elements instead of String, will likely to improve 
   performance by eliminating memory churn.

3. Re-implement the Taglet API to use doctree, providing better
   and accurate diagnostics, better handling of comment prefixed
   " * " prefixed lines. Replacement of doctree allows 
   implementation of features such as HTML auto correction in
   the future.

4. Re-implement the APIs to use Collections and/or Streams,    
   providing an efficient implementation using system resources
   effectively.

Dependencies
------------
None at this time

Impact
------
Standard Doclet which is a client of Doclet.

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