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

[Jonathan Gibbons]

On Fri, 17 Nov 2023 13:01:58 GMT, Pavel Rappo <prappo 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) 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