> 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
> co...
Jonathan Gibbons has updated the pull request with a new target base due to a
merge or a rebase. The incremental webrev excludes the unrelated changes
brought in by the merge/rebase. The pull request contains three additional
commits since the last revision:
- Address review feedback
- Merge remote-tracking branch 'upstream/master' into 8320207.nested-code
- JDK-8320207: doclet incorrectly chooses code font for a See Also link
-------------
Changes:
- all: https://git.openjdk.org/jdk/pull/16699/files
- new: https://git.openjdk.org/jdk/pull/16699/files/75aeb6c0..597b8f10
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk&pr=16699&range=01
- incr: https://webrevs.openjdk.org/?repo=jdk&pr=16699&range=00-01
Stats: 15949 lines in 485 files changed: 8945 ins; 3487 del; 3517 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
