On Thu, 16 Nov 2023 22:09:34 GMT, Jonathan Gibbons <[email protected]> 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...
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/SeeTaglet.java
line 198:
> 196: * {@return {@code true} if the label should be rendered in plain
> font}
> 197: *
> 198: * The method uses a heuristic, to see string form of the label is a
> substring of the reference.
Suggestion:
* The method uses a heuristic, to see if the string form of the label is a
substring of the reference.
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/SeeTaglet.java
line 223:
> 221: * @param label the label
> 222: */
> 223: private boolean isPlain(String refSignature, List<? extends DocTree>
> label) {
Should we reflect any part of this machinery in the
[specification](https://docs.oracle.com/en/java/javase/21/docs/specs/javadoc/doc-comment-spec.html#see),
which is currently silent on presentation details of `@see`?
test/langtools/jdk/javadoc/doclet/testSeeTag/TestSeeTagFont.java line 2:
> 1: /*
> 2: * Copyright (c) 2002, 2023, Oracle and/or its affiliates. All rights
> reserved.
2002?
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/16699#discussion_r1397270102
PR Review Comment: https://git.openjdk.org/jdk/pull/16699#discussion_r1397265614
PR Review Comment: https://git.openjdk.org/jdk/pull/16699#discussion_r1397233849
