Provide a new comment tag to specify the summary of an API 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