Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8203494

Improve javadoc tag specification.

    XMLWordPrintable

    Details

    • Type: CSR
    • Status: Closed
    • Priority: P3
    • Resolution: Approved
    • Fix Version/s: 12
    • Component/s: tools
    • Labels:
      None
    • Subcomponent:
    • Compatibility Risk:
      minimal
    • Interface Kind:
      File or wire format

      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

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

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              jjg Jonathan Gibbons
              Reporter:
              ksrini Kumar Srinivasan
              Reviewed By:
              Joe Darcy
              Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: