On Fri, 17 Nov 2023 13:01:58 GMT, Pavel Rappo <pra...@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) mod...
>
> 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.
thanks; fixed
> 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`?
I'm writing a CSR.
> 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?
Fixed.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/16699#discussion_r1397947803
PR Review Comment: https://git.openjdk.org/jdk/pull/16699#discussion_r1397948196
PR Review Comment: https://git.openjdk.org/jdk/pull/16699#discussion_r1397947070
