On Thu, 16 Nov 2023 22:09:34 GMT, Jonathan Gibbons <j...@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...
Looks good to me. Although this seems like an intricate solution for what at
first sight looks like a simple issue, the actual occurrences in our code base
show there's an actual problem to be solved.
Although this looks like something that could "just work", like Pavel I wonder
if this should be documented in the spec.
-------------
Marked as reviewed by hannesw (Reviewer).
PR Review: https://git.openjdk.org/jdk/pull/16699#pullrequestreview-1737425818
