Please review a change to the font used to display the content of an `@see` tag.
The underlying trigger for this is in `ClassFileFormatVersion.java` which
contains
`@see System#getProperties System property {@code java.class.version}`
The (reasonable) presumption is that by default the label will be in plain
font, except for the trailing `{@code...}` tag.
Because `SeeTaglet` always generates a link with code font, the nested tag
gives a nested `<code>...</code>` element, which is reported as an error by
`html-tidy`.
However, there are numerous examples in the JDK report where there is a
less-reasonable presumption that the output _will_ be in code font. This is
often used to give a "slightly different" rendering of the target, such as
omitting the parentheses and any parameters from a link to a method. There are
too many such examples to easily change, even though it would be better to do
so for consistency.
The dilemma is resolved in favor of not using code font when the label looks
like a phrase and not a form of the target signature, on the grounds that it is
better to omit `<code>...</code>` and allow the author to opt-in to using code
font either explicitly or with a `{@code tag}`, since there is no way of
opt-out of being in code font within the content of the element.
Thus, the fix is a change to `SeeTaglet` which analyses the label to see if it
appears to be a phrase of some sort, and not a form of a reference to the
target. If it appears to be a phrase, code font is not used; if it appears to
be a reference to the target, code font is used.
Note: initially, the solution was more focussed on examining the label in more
detail and matching it more accurately with the reference, but there are enough
variations in the JDK code that this was deemed impractical. The solution to
focus on whether the label looks like a phrase is simpler and more reliable.
This does change the font used for some links in the JDK documentation,
including the link in `ClassFileFormatVersion` described above. (Only the
font, as indicated by the use of `<code>` is changed, never the target URL or
the text of the link.) Many of the other changes are as expected, such as links
to "security properties" or "Types and Elements". There are a few places where
the label text is a mixture of a signature and an explanation, which used to be
all in code font and is now all in plain font. For these cases, it would be
good to (separately) modify the label to explicitly use code font around the
relevant parts of the label. As an example of these "mixed use" tags, see the
following in `com.sun.jdi.Type`
* @see PrimitiveType Subinterface PrimitiveType
* @see ReferenceType Subinterface ReferenceType
* @see Value Value - for relationship between Type and Value
* @see Field#type() Field.type() - for usage examples
```
-------------
Commit messages:
- JDK-8320207: doclet incorrectly chooses code font for a See Also link
Changes: https://git.openjdk.org/jdk/pull/16699/files
Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=16699&range=00
Issue: https://bugs.openjdk.org/browse/JDK-8320207
Stats: 290 lines in 6 files changed: 263 ins; 0 del; 27 mod
Patch: https://git.openjdk.org/jdk/pull/16699.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/16699/head:pull/16699
PR: https://git.openjdk.org/jdk/pull/16699
