RFR: JDK-8262992: Improve `@see` output [v2]

[Jonathan Gibbons]

On Tue, 9 Mar 2021 16:23:26 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> This changes the output for `@see` tags to a `<ul>` structure. A different CSS style is used if any of the `@see` tag labels are longer than 30 characters or contain a comma. 
>> 
>> The layout for the default CSS style is similar to the one we had so far with multiple links displayed inline and separated by commas. The CSS style for lists containing longer labels displays the list in block mode, but still separated by commas and without list markers. Note that the commas are generated via CSS in both cases.
>> 
>> As expected, there's a lot of test churn with this change. I converted some tests to text blocks that were still using old style string concatenation. In `TestSingletonLists.java` I had to exclude `@see` lists from the singleton check as javadoc generates a "See also" item for constant field values.
>
> Hannes Wallnöfer has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Update `@see` tag in class java.security.cert.PKIXRevocationChecker

Nice!  I like the basic change to `TagletWriterImpl`.

Close to being approved, but there are some minor comments inline for disciussion or to be addressed.

src/java.base/share/classes/java/security/cert/PKIXRevocationChecker.java line 97:

> 95:  * @see <a href="http://www.ietf.org/rfc/rfc5280.txt"><i>RFC 5280:
> 96:  * Internet X.509 Public Key Infrastructure Certificate and Certificate
> 97:  * Revocation List (CRL) Profile</i></a>

It's not wrong, but the use of `<i>...</i>` is non-standard.  But, while we should split the malformed entry, it's arguably out of scope to tweak the style.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java line 148:

> 146:     // Threshold for length of @see tag label for switching from inline to block layout.
> 147:     private static final int SEE_TAG_MAX_INLINE_LENGTH = 30;
> 148: 

For future consideration, we should look at encoding numbers like this in a config file.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlStyle.java line 361:

> 359:      */
> 360:     seeListLong,
> 361: 

The list is alpha-sorted in each group, suggesting that these new entries should go before `serializedClassDetails`.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css line 346:

> 344:     content: ", ";
> 345:     white-space: pre-wrap;
> 346: }

Cool! I didn't know you could do that. Is this widely supported?

test/langtools/jdk/javadoc/doclet/testConstructors/TestConstructors.java line 63:

> 61:                     </ul>
> 62:                     </dd>""",
> 63:                 """

Nice new rendering ... i.e. the general use of `<ul>`

test/langtools/jdk/javadoc/doclet/testLinkOption/pkg/B.java line 64:

> 62:     * Literal IPv6 Addresses in URLs</i></a>
> 63:     * @see <a href="C.html">A nearby file</a>
> 64:     */

Wow, I didn't know we had "bad" examples in the test code.   If there isn't one already, can you file an issue for me to updated DocLint with a check for this?

test/langtools/jdk/javadoc/doclet/testSingletonLists/TestSingletonLists.java line 270:

> 268:                     if ("see-list".equals(attrs.get("class"))) {
> 269:                         inSeeList = true;
> 270:                     }

This is OK for now, because the lists from `@see` tags cannot be nested. But, I had a similar problem in my work yesterday, and so going forward we might want a more general solution to track the class of each list on the stack.

test/langtools/jdk/javadoc/doclet/testSingletonLists/TestSingletonLists.java line 287:

> 285:                     Map<String,Integer> c = counts.pop();
> 286:                     if (inSeeList) {
> 287:                         // Ignore "Constant Field Values" @see items for final fields created by javadoc

I think the comment is too specific. Won't the problem also be triggered for classes with a single `@see` and no constant values?  It m might also be triggered on serializable classes, with the link to the `Serialized Form`.

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

PR: https://git.openjdk.java.net/jdk/pull/2894