Inline tags for marking program elements: {@class}, {@method}, {@field}, {@arg}

Name: rmT116609 Date: 07/13/2004

A DESCRIPTION OF THE REQUEST :
I saw that @code and @literal have been added, as of 1.5 which is great news. There are other common things that we document that would benefit from more explicit markup. This would allow them to be colored in coustom ways using a stylesheet and also linked as needed:

  @class
    : inline tag
    : follow by a class name (normal resolution rules apply)
    : generate links as needed and imbed in a <span> element allowing the stylesheet to distinctively display class names
    : example:
      This is an implementation of {@class Comparator} that sorts by getMax()

  @method
    : inline tag
    : follow by a method name (normal resolution rules apply)
    : generate links as needed and imbed in a <span> element allowing the stylesheet to distinctively display method names
    : example:
      This is an implemenmtation of Comparator that sorts by {@method getMax()}

  @field - as for @method and @class

  @arg
    : inline tag in constructors and methods only
    : followed by the name of one of the parameters on the currently documented method or constructor
    : example
      @return the maximum value of {@arg obj1}, and {@arg obj2}.
      @throws ClassCastException if either {@arg1} or {@arg2} are of an incompattible type

The @arg tag would be particularly helpfull, as often the argument names are common words that also appear in the description. Perhaps it would be better named @param, but that's already taken. @paramRef?

JUSTIFICATION :
Explicitly marking up references to the names of code elements in the javadoc helps keep the whole thing integrated. IDEs have a better chance of sanity checking documentation, and the document generators (e.g. javadoc) can embed more targeted markup.


CUSTOMER SUBMITTED WORKAROUND :
In the javadoc, embed <span> and <class> and @link elements. But, this gets realy ugly realy quickly.
(Incident Review ID: 285703)
======================================================================