Details

    • Author:
      Jonathan Gibbons
    • JEP Type:
      Feature
    • Exposure:
      Open
    • Subcomponent:
    • Scope:
      JDK
    • Discussion:
      javadoc dash dev at openjdk dot java dot net
    • Effort:
      M
    • Duration:
      M
    • Alert Status:
       Green
    • JEP Number:
      221

      Description

      Summary

      Replace the Doclet API with a simpler design that leverages newer alternative APIs with improved functionality, and update the standard doclet to use it.

      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 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.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 standard doclet will be improved as a result of this work.

      Motivation

      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.

      Description

      The new Doclet API uses the Language Model API and Source Tree API.

      The javadoc tool is updated to recognize doclets written against the new API. The old 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 standard doclet is updated in accordance with the new API, and the majority of the work for this project, 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 were two versions of the Taglet API, one public and one internal. The public version has been modified to use the Language Model and Source Tree APIs.

      It is known that there are some existing user-written doclets that directly reference code in 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, 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.

      Testing

      A few tests were developed for newer use-cases.

        Issue Links

          Activity

          Hide
          mtrudeau Michel Trudeau added a comment -
          This is a candidate for 9.
          Show
          mtrudeau Michel Trudeau added a comment - This is a candidate for 9.

            People

            • Assignee:
              ksrini Kumar Srinivasan
              Reporter:
              ksrini Kumar Srinivasan
              Owner:
              Kumar Srinivasan
              Reviewed By:
              Brian Goetz, Jonathan Gibbons
              Endorsed By:
              Brian Goetz
            • Votes:
              0 Vote for this issue
              Watchers:
              6 Start watching this issue

              Dates

              • Due:
                Created:
                Updated:
                Integration Due: