-
Enhancement
-
Resolution: Fixed
-
P3
-
22
-
None
-
b08
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.
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.