JDK-8203494 : Improve javadoc tag specification.
  • Type: CSR
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Priority: P3
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 12
  • Submitted: 2018-05-21
  • Updated: 2018-08-30
  • Resolved: 2018-08-24
Related Reports
CSR :  
JDK-8186260 - Improve javadoc tag specification.
Relates :  
JDK-8210245 - Review URLs in javadoc Tag Specification
Relates :  
JDK-8164408 - Add module support for @see, @link and @linkplain javadoc tags.
Relates :  
JDK-8210244 - {@value} should be permitted in module documentation
Description
Summary
-------

Replace the summary at the end of the _Documentation Comment Tag Specification_.

Problem
-------

The summary, as currently written, contains bugs, and is not as convenient to read as it could be. 

Solution
--------

The summary is currently written as a list of short sections. It can be
better represented as a table, showing which tags are available in each context.

Those bugs that exist purely in the specification itself will be fixed. For example, a number of tags were shown as inline tags (within `{  }`) whereas in reality they are block tags.

The new table shows up some irregularities in the implementation as well as the specification; those issues will be addressed separately.

Specification
-------------

The section headed "Where Tags Can Be Used" will be replaced in its entirety.  

The raw Markdown for the new text is attached as `spec-update.txt`.  

The full new specification, in HTML format, is attached as `doc-comment-spec.html`. (Note, the stylesheet is not included; the visual presentation may differ depending on the actual stylesheet used.)  The specification, with stylesheet, can be viewed online at [http://cr.openjdk.java.net/~jjg/8186260/spec/specs/doc-comment-spec.html](http://cr.openjdk.java.net/~jjg/8186260/spec/specs/doc-comment-spec.html)

_Note: JBS seems remarkably unable to display the change inline, either as raw Markdown in a code block, or as part of this Description._
Comments
Yes, this was just a reorg of the spec text, and yes, it revealed the need for enhancements (@see/@link) and bug fixes (@value)
24-08-2018
Moving to Approved with some comments for follow-up work. Should the @see and @link tags include some optional syntax to specify a module? Something like @see [module-name/]package.class#member label would be consistent with other syntax expansions to accommodate modules. There are URLs to documents associated with older version of the platform: " See Documenting Serializable Fields and Data for a Class at http://docs.oracle.com/javase/8/docs/platform/serialization/spec/serial-arch.html#5251 See also Oracle's Criteria for Including Classes in the Serialized Form Specification at http://www.oracle.com/technetwork/java/javase/documentation/serialized-criteria-137781.html" Is there a rationale for not allowing {@value} in a module?
24-08-2018