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

Improve references to tags in the Doc Comment Spec

    XMLWordPrintable

Details

    • Enhancement
    • Resolution: Fixed
    • P3
    • 23
    • 22
    • tools
    • None

    Description

      Until now, in the Doc Comment Spec, we have used characters sequences like `@see` to refer to a block tag and `{@link}` to refer to an inline tag.

      The convention is beginning to wear out. We support both `@return` and `{@return}` and have no convenient single way to refer to either form. And, using a form like `{@link}` is bordering on ambiguous ... does it mean an instance of the link (which in this case would be an error, with no referent), or does it mean the general concept of that tag. The situation is exacerbated by the recently changes to the `inheritDoc` tag, which may, but need not, have arguments, so that `{@inheritDoc}` may well be ambiguous.

      The proposal is to drop `@` and `{...}` when referring to the abstract form of a tag, and to only use those characters when providing specific syntactic examples.

      Attachments

        Activity

          People

            prappo Pavel Rappo
            jjg Jonathan Gibbons
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

            Dates

              Created:
              Updated:
              Resolved: