On Fri, 20 Dec 2024 15:02:17 GMT, Nizar Benalla <[email protected]> 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
