Integrated: JDK-8320207: doclet incorrectly chooses code font for a See Also link

[Jonathan Gibbons]

On Thu, 16 Nov 2023 22:09:34 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

> 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...

This pull request has now been integrated.

Changeset: 407cdd4c
Author:    Jonathan Gibbons <jjg at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/407cdd4cac4c78c50d5f27299d6d65e082a966ca
Stats:     290 lines in 6 files changed: 263 ins; 0 del; 27 mod

8320207: doclet incorrectly chooses code font for a See Also link

Reviewed-by: hannesw

-------------

PR: https://git.openjdk.org/jdk/pull/16699