JDK-8184034 : Provide a new comment tag to specify the summary of an API description.
  • Type: CSR
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Priority: P3
  • Status: Closed
  • Resolution: Approved
  • Fix Versions: 10
  • Submitted: 2017-07-07
  • Updated: 2017-11-30
  • Resolved: 2017-07-19
Related Reports
CSR :  
JDK-8173425 - Javadoc needs a new tag to specify the summary.
Description
Summary
-------

Provide a new comment tag to specify the summary of an API description.

Problem
-------

Currently, the standard doclet treats the first sentence of an API description as a
summary that can be used in various places in the documentation. The first sentence
is currently inferred using either a simple algorithm or java.text.BreakIterator.
The heuristics are not always correct, and so it would be convenient to be able
to explicitly specify the text to be used as the summary of the API description.

Solution
--------

Introduce a new comment tag @summary whose content will be used as the
summary of the API description.

Specification
-------------
The specdiffs are attached for the record, but for convenience here are the
web links to the specs:

Compile Tree APIs changes: http://cr.openjdk.java.net/~ksrini/8173425/specdiff.dir/tree-spec/overview-summary.html

Comment tag specification: http://cr.openjdk.java.net/~ksrini/8173425/specdiff.dir/doc-comment-spec/diff.html
Comments
[~darcy] DocTreeScanner.visitSummary should not be defined to call visitOther, because the overriding class level docs specify that the purpose of scanner classes is to visit children. A summary node has children, and so I think it would be wrong to do anything other than visit the children and reduce the results.
30-11-2017
A case could be made that DocTreeScanner.visitSummary should be defined to call visitOther, but I think the current definition is okay. Moving to approved.
19-07-2017
In the API, the new declarations should all be labeled '@since 10'. The new visitSummary method should be a default method that calls visitUnknowm (See ElementVisitor for an example.) Separately, other items that were added in 9 should be reviewed and updated.
13-07-2017