RFR: 8337111: Bad HTML checker for generated documentation [v6]

[Hannes Wallnöfer]

On Fri, 20 Dec 2024 15:02:17 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Doccheck's human-generated reports are great at previewing a "chessboard" of results. Giving reader a quick glimpse at the quality/health of the documentation. But these tests needed to be automated and they didn't easily translate to something that can be integrated into a CI.
>> 
>> This PR includes an HTML and internal link test on `api/java.base` and a BadChars and Doctype test on the entire generated documentation bundle.
>> 
>> Here is an example of the output after running all tests on `api/java.base`
>> 
>> Note: There is an active PR to fix the broken anchors left in `java.base` so this is not a blocker.
>> 
>> 
>> 
>> STDOUT:
>> STDERR:
>> test: test
>> Tidy found errors in the generated HTML
>> /Users/nizarbenalla/Work/jdk-repos/jdk1/build/macosx-aarch64/images/docs/api/java.base/java/lang/Class.html:323:87: Warning: <a> anchor "nest" already defined
>> Tidy output end.
>> 
>> 
>> api/java.base/java/util/concurrent/StructuredTaskScope.ShutdownOnFailure.html:245: id not found: api/java.base/java/util/concurrent/StructuredTaskScope.ShutdownOnFailure.html#TreeStructure
>> api/java.base/java/util/concurrent/StructuredTaskScope.ShutdownOnSuccess.html:242: id not found: api/java.base/java/util/concurrent/StructuredTaskScope.ShutdownOnSuccess.html#TreeStructure
>> api/java.base/java/lang/Class.html:323: name already declared: nest
>> api/java.base/java/lang/Module.html:291: id not found: api/java.base/java/lang/foreign/package-summary.html#restricted
>> api/java.base/java/lang/Module.html:434: id not found: api/java.base/java/lang/foreign/package-summary.html#restricted
>> api/java.base/java/lang/foreign/MemorySegment.html:725: id not found: api/java.base/java/lang/foreign/package-summary.html#restricted
>> 
>> Link Checker Report
>> Checked 3446 files.
>> Found 445059 references to 48205 anchors in 5770 files and 64 other URIs.
>>      1 duplicate ids
>>      3 missing ids
>> 
>> Hosts
>>     20 docs.oracle.com
>>      1 tools.ietf.org
>>      1 www.ietf.org
>>      1 jcp.org
>>      4 www.rfc-editor.org
>>      7 unicode.org
>>     10 www.unicode.org
>>     20 www.w3.org
>> Exception running test test: java.lang.Exception: One or more HTML checkers failed: [java.lang.RuntimeException: Tidy found errors in the generated HTML, java.lang.RuntimeException: LinkChecker encountered errors. Duplicate IDs: 1, Missing IDs: 3, Missing Files: 0, Bad Schemes: 0]
>> java.lang.Exception: One or more HTML checkers failed: [java.lang.RuntimeException: Tidy found errors in the generated HTML, java.lang.Ru...
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   fix whitespace

test/docs/jdk/javadoc/doccheck/doccheckutils/checkers/ExtLinkChecker.java line 55:

> 53:         extLinks.addAll(input.lines()
> 54:                 .map(line -> line.replaceAll("\\@\\@JAVASE_VERSION\\@\\@", String.valueOf(Runtime.version().feature())))
> 55:                 .filter(line -> !line.startsWith("#"))

Nitpicking for mostly aesthetic reasons, but it would be nice to do the filter before the map, and pull the `String.valueof(...)` out into a variable.

test/docs/jdk/javadoc/doccheck/doccheckutils/checkers/ExtLinkChecker.java line 110:

> 108: 
> 109:             // The checker runs into a problem with links that have more than one hash character.
> 110:             // You cannot create a URI unless you convert the second hash character into

Unfinished sentence, you could say "... unless the second hash is escaped."

test/docs/jdk/javadoc/doccheck/doccheckutils/checkers/LinkChecker.java line 367:

> 365:     }
> 366: 
> 367:     static class URIComparator implements Comparator<URI> {

It looks like this class is unused, is there a need for it given that `URI` implements `Comparable`?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/21879#discussion_r1894101103
PR Review Comment: https://git.openjdk.org/jdk/pull/21879#discussion_r1894102493
PR Review Comment: https://git.openjdk.org/jdk/pull/21879#discussion_r1894091269