Draft JEP: Javadoc Tag enhancements

[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 Tag Enhancements
Author: Kumar Srinivasan
Organization: Oracle Corp.
Owner: Kumar Srinivasan
Date: 2014/03/04
State: Draft
Exposure: Open
Type: Research
Component: tools/javadoc
Scope: JDK
JSR: 
RFE:
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
-------
Introduce new tags for the javadoc tool, to support more efficient and accurate authoring of interface specifications.

Goals
-----
Provide a specific set of new tags which improves expressiveness readability and specificity, as well as reducing redundant text, while authoring API documentation for the javadoc tool.

It is a non-goal to changes the current build infrastructure, in
any shape, or utilize these enhancements in the Java API documentation.

Motivation
----------
The current implementation of the tags makes it very inconvenient and error prone to include code examples in the
documentation, formatting mistakes are common and it is
difficult to enforce the validity or correctness of code
examples through compilation or testing.

The API documentation treats the first sentence specially, then
divides the documentation into one or more block tags, making it
hard to separate normative text from merely informative text,
both of which are useful to readers. It is also difficult to
separate descriptive text pertaining to the interface from that
of the implementation.

There are many situation where documentation text is effectively
repeated in slightly different forms, not only is this
cumbersome for the API author, but provides a vector, by which
inconsistencies can creep into the API documentation.

Description
-----------
The following items will be explored:

1. Introduce an @include tag, which would include text from 
   another external location such as an "examples" directory, 
   allowing for the following:
     a. location of the file containing the text to be included
     b. bounds of the text using some absolute numbers or 
        regular expressions 
     c. presentation or style such as syntax highlighting of
        the text to be rendered
     d. an option to disable or enable line numbers if desired
   
2. In JDK8 user-defined block tags @apiSpec, @apiNote, 
   @implSpec, at implNote were used, this exists within the current    
   framework, and can be used to express normative and 
   informative texts. The former being interesting to the API  
   implementor or a Conformance tester, and informative text, 
   interesting to the user or client of the interface. Having 
   such tags will enable a tool such as javadoc, to process and 
   render these tags elegantly and uniformly with different 
   fonts and/or style for each of these.

3. Enhance @inheritDoc -> @includeDoc, ie. provide control for 
   specifying inheritance of the document comments. For 
   example: the comment for a method in a base class may not be 
   applicable to the extended form of the method in the 
   subclass.
 
4. Allow re-use of named blocks. Repetitive descriptions are 
   used for throws clauses, JavaDoc could provide a new tag 
   which allows inclusion of inlined named text segments within 
   a document.

5. @externalspec or an enhanced @see tag, whereby external 
   specifications such as RFCs, etc., can be referenced.

6. Remove repetitious "Returns" statements, for example, getter 
   methods have repeated  "Returns some object and @return some 
   object". An enhanced tag such as {@ return an Object.....}, 
   would avoid these repetitions.

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

Impact
------
None at this time

Testing
-------
New tests will need to be developed to test all possible
use-cases.