Summary

Change the font used to display some "See Also:" links.

Problem

The Standard Doclet always displays the content of @see tags for program elements in monospace font. This is inappropriate in cases where the label that is given is a short natural-language phrase instead of just indicating the program element that is the target of the link.

In addition, examination of the JDK code base indicates that there are uses of the @see tag where the label is a natural-language phrase (such that plain font is appropriate), and others where the label is an abbreviated form of the signature (such that monospace font is appropriate). There are also some instances of @see tags where parts of the label are best displayed in normal font, and some parts are best displayed in monospace font. The use of a <code> element to display all of the label in monospace font is problematic because it is not possible to revert to "plain" font within the element.

In running text, an author has the choice of using {@link ....} or {@linkplain ...} to indicate the font to be used for the link. That is not an option here, and introducing a new tag or syntactic variant of the @see tag would be too much of an incompatible change.

Solution

The content of the label is examined, to determine whether to use plain font or monospace font.

Specification

Along with some otherwise cosmetic changes, the following sentence will be added to the third bullet of the specification of the @see tag in the Document Comment Specification for the Standard Doclet.

If the content of the label appears to be a phrase, and not just a possibly-abbreviated form of a reference to the link target, the link will be displayed in plain font; otherwise, the link will be displayed in monospace font.