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

Note: JBS seems remarkably unable to display the change inline, either as raw Markdown in a code block, or as part of this Description.