Bug ID: JDK-4097252 Add syntax to generate in-line @see links in descriptions and tag text

Type: Enhancement
Component: tools
Sub-Component: javadoc(tool)
Affected Version: 1.1,1.1.3,1.2.0

Priority: P4
Status: Closed
Resolution: Fixed
OS:
solaris_2.5,solaris_2.5.1,windows_95 solaris_2.5,solaris_2.5.1,windows_95
CPU: generic,x86,sparc

Submitted: 1997-12-05
Updated: 2014-05-05
Resolved: 1999-01-19

Other
1.2.0 1.2beta4Fixed

The @deprecated tag currently looks like this
 
 /**
  * Description...
  *
  * @deprecated  Replaced by setEnabled(boolean)
  */
  disable() {
    // implementation
  }

When you generate the HTML, the result looks like:

  <a>java.awt.Component.disable()</a> replaced by setEnabled(boolean)  

where "disable" has a link but "setEnabled" does not.

We need a new delimiter added to the @deprecated argument that indicates
to javadoc that a link should be added to "setEnabled".

We sometimes refer to this feature as "in-line @see tags".

CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: 1.2beta4 FIXED IN: 1.2beta4 INTEGRATED IN: 1.2beta4 VERIFIED IN: 1.2beta4
14-06-2004
SUGGESTED FIX The solution to this might also be used where we want links in the middle of descriptions. Option 2 below would be the a unique delimiter for this. Several ideas come to mind: 1) Put the text to be linked inside quotes: @deprecated Replaced by "setEnabled(boolean)" 2) Put the text to be linked inside an HTML-looking tag that only javadoc understands: @deprecated Replaced by <jdlink>setEnabled(boolean)</jdlink> (jdlink is kind of long -- we want it to be non-intrusive) 3) Use some unique combination of braces and/or brackets: @deprecated Replaced by <<setEnabled(boolean)>> Two angle brackets "<<" is a good choice because doc comments are supposed to be written in HTML, and these two characters are illegal in HTML since you cannot nest HTML tags. Murray Altheim prefers we avoid "<" altogether because it is recognized as the tag delimiter for HTML. 4) Use the "@" sign to "remind" developers that this is javadoc syntax, and not some obscure HTML feature. Enclose it in curly braces to give it scope: @deprecated Replaced by {@see setEnabled(boolean)} However, although it performs the same function as @see, it does not put the name in the "See Also" list, so perhaps we should call it by a different name, such as "href" or "link": @deprecated Replaced by {@link setEnabled(boolean)} We also want to enable an optional label to be included: @deprecated Replaced by {@link setEnabled(Boolean) setEnabled method} The first space outside balanced parentheses is the separator. NOTE: When the "@" symbol appears at the start of a line, it denotes a new tag. Using "{@" ensures that this does not start a new tag, but starts an inline tag. See "Public Summary" for the full proposal.
11-06-2004
PUBLIC COMMENTS This feature extends the javadoc "doc comment language" from ordinary tags to inline tags. This is submitted as RFE 4097252. PROPOSAL To add to JDK 1.2 a mechanism for duplicating the @see tag but inside arbitrary text (doc comment descriptions and text belonging to tags such as @deprecated). This would be used to add links to API names in text, something which can be done today only with hard-coded HTML. PROBLEM THIS PROPOSAL SOLVES Currently the only way in Javadoc to include links to API is to use the @see tag or to hard-code HTML. The former is a standalone tag that cannot be used inside a paragraph description. The latter is impractical, being time-consuming to enter, interferes with the readability of doc comments in a source file, and relies on a specific output directory structure of javadoc (which we are changing from flat to hierarchical in JDK 1.2). For example, this proposal would solve the problem where the @deprecated tag cannot easily include a link to the replacement API. (The @deprecated tag takes only one argument, which is text.) /** * @deprecated The method getMonth is replaced by the * Calendar.get(int) method. / ^^^^^^^^^^^^^^^^^ WANT A LINK HERE In-line tags would also allow us to generate cross-references in FrameMaker (derived from in-line tags in doc comments) when we later create the MIF doclet. PROBLEMS WITH INITIAL PROPOSAL We initially proposed double-angle-brackets for the syntax: <<apiname>>. After feedback from HTML/XML/SGML experts Bill Foote and Murray Altheim and much deliberation with Tim Lindholm and Mark Reinhold, it's become clear that while it is concise, <<apiname>> is not the optimum syntax for inline links in doc comments: - It does not allow for extensibility - It does not use the '@' character (that connotes "javadoc") and so is not immediately recognized as part of the javadoc syntax - Because it uses the HTML delimiter "<", it is not benignly processed by browsers and HTML parsers (This is important for people writing their own doclets who need to parse the HTML.) NEW PROPOSAL We've come up with a syntax that satisfies these requirements, which begins with "{@" and has its scope defined by curly braces: No-label form: {@link apiname} Label form: {@link apiname label} - "apiname" is the class, interface, method, field or constructor name. - "label" is optional and is any arbitrary text. - A space is the delimiter between apiname and label. - Whitespace is allowed inside parentheses in the apiname. - If you need to use "}" in the label, use the HTML character } If the label is omitted, the apiname is used as the label. There is no limit to the number of {@link} tags allowed in a sentence. They can be used in the description part of a doc comment or in the text portion of a tag (such as @deprecated). This syntax is general enough to allow us to extend it to other cases where we need links. One case in mind is eventually when we add categories to the language, perhaps as the @category tag. You might tag the static field RED with "@category COLOR" and then in a method that takes a color parameter, you would specify the doc comment "@param color Use one of COLOR" where you want COLOR to be a link to the list of static field colors. The syntax might be: "@param color Use one of {@category COLOR}". We thought of using {@see ...} but decided this new functionality is different enough to take a different name (it does not insert a "See also" heading, nor does it group multiple @see tags). In the standard doclet, the above syntax generates something like the following (it resolves "apiname" to the proper output file): <a href="apiname">label</a> EXAMPLES Example with no label: Doc comment: /* * Replaced by {@link setEnabled(boolean)} / HTML output: Replaced by <a href="#setEnabled(boolean)">setEnabled(boolean)</a> Example with label: Doc comment: /* * Replaced by {@link setEnabled(boolean) setEnabled method} */ HTML output: Replaced by <a href="#setEnabled(boolean)">setEnabled method</a> NOTE 1: When the "@" symbol appears at the start of a line, it denotes a new tag. Using "{@" ensures that the "@" cannot start a new line. NOTE 2: A natural extension of the label feature is that the old @see tag can now have a label: @see setEnabled(boolean) setEnabled method doug.kramer@Eng 1998-04-03
03-04-1998
EVALUATION I've changed the synopsis from: Add link in @deprecated to replacement API to: Add syntax to generate links in tags and comments Since this is just as easy to implement in the general case and is useful in the wider context. robert.field@Eng 1997-12-04 We've chosen suggested fix #4. doug.kramer@Eng 1998-04-02 I modified the synopsis again to make this RFE easier to search for. doug.kramer@Eng 1998-04-03
04-12-1997

Duplicate :	JDK-4034233 - Add @xref doc-comment tag (similar to @link)
Duplicate :	JDK-4102072 - Add information about replacement API in Deprecated API List
Duplicate :	JDK-4115787 - Mapping of e-mail addresses within @authour tags
Duplicate :	JDK-4034267 - javadoc template: Add automatic link capability within descriptions