<i18n dev> RFR: 8336039: Doccheck: HTML warnings, broken links and missing files in java.base documentation [v2]

[Chen Liang]

On Fri, 19 Jul 2024 13:08:06 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Can I get a review for this change that fixes some broken links in javadoc comments? The new docs are hosted [here](https://cr.openjdk.org/~nbenalla/GeneratedDocs/8336039-warnings-links/).
>> 
>> It's mostly fixing some relative links.
>> If using `{@docroot}` isn't ideal I can change it.
>> 
>> Here is the result of running `diff -r docs-master docs` on the docs from master vs and after these changes 
>> 
>> 
>> diff -r docs-master/api/java.base/java/lang/classfile/components/CodeStackTracker.html docs/api/java.base/java/lang/classfile/components/CodeStackTracker.html
>> 106c106
>> <  <p>
>> ---
>>>  </p>
>> diff -r docs-master/api/java.base/java/lang/classfile/package-summary.html docs/api/java.base/java/lang/classfile/package-summary.html
>> 99c99
>> <  <p>
>> ---
>>> 
>> 106c106
>> <  <p>
>> ---
>>> 
>> 618c618
>> <  <p>
>> ---
>>> 
>> 755c755
>> <  <p>
>> ---
>>> 
>> 783c783
>> < <p>
>> ---
>>> 
>> diff -r docs-master/api/java.base/java/lang/foreign/Arena.html docs/api/java.base/java/lang/foreign/Arena.html
>> 142c142
>> <  the segments allocated by it) becomes <a href="../../../java/lang/ref/package.html#reachability">unreachable</a>,
>> ---
>>>  the segments allocated by it) becomes <a href="../../../java/lang/ref/package-summary.html#reachability">unreachable</a>,
>> diff -r docs-master/api/java.base/java/lang/foreign/MemorySegment.Scope.html docs/api/java.base/java/lang/foreign/MemorySegment.Scope.html
>> 120c120
>> <  as long as it is <a href="../../../java/lang/ref/package.html#reachability">reachable</a>.
>> ---
>>>  as long as it is <a href="../../../java/lang/ref/package-summary.html#reachability">reachable</a>.
>> diff -r docs-master/api/java.base/java/lang/foreign/MemorySegment.html docs/api/java.base/java/lang/foreign/MemorySegment.html
>> 1420c1420
>> <           kept <a href="../../../java/lang/ref/package.html#reachability">reachable</a>
>> ---
>>>           kept <a href="../../../java/lang/ref/package-summary.html#reachability">reachable</a>
>> 1833c1833
>> <           <a href="../../../java/lang/ref/package.html#reachability">unreachable</a>.
>> ---
>>>           <a href="../../../java/lang/ref/package-summary.html#reachability">unreachable</a>.
>> 1899c1899
>> <           <a href="../../../java/lang/ref/package.html#reachability">unreachable</a>.
>> ---
>>>           <a href="../../../java/lang/ref/package-summary.html#reachability">unreachable</a>.
>> diff -r docs-master/api/java.base/java/lang/foreign/SymbolLookup.html docs/api/java.base/java/lang/foreign/SymbolLookup.html
>> 395c395
>> ...
>
> Nizar Benalla has updated the pull request incrementally with one additional commit since the last revision:
> 
>   remove docroot based on review

src/java.base/share/classes/java/lang/classfile/components/CodeStackTracker.java line 40:

> 38:  * <p>
> 39:  * Sample use:
> 40:  * <p>

This `<p>` intends to add a break. So I think you can just remove this new paragraph, like you've done below.

src/java.base/share/classes/java/lang/foreign/Arena.java line 64:

> 62:  * such, the regions of memory backing memory segments allocated with the automatic arena
> 63:  * are deallocated at some unspecified time <em>after</em> the automatic arena (and all
> 64:  * the segments allocated by it) becomes <a href="../../../java/lang/ref/package-summary.html#reachability">unreachable</a>,

Suggestion:

 * the segments allocated by it) becomes {@linkplain java.lang.ref##reachability unreachable},

same for other occurrences.

src/java.base/share/classes/java/text/MessageFormat.java line 374:

> 372:  * In internationalized programs, the message format pattern and other
> 373:  * static strings will likely be obtained from resource bundles.
> 374:  * </p>

Same here, just remove `<p>` instead of adding a closing

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

PR Review Comment: https://git.openjdk.org/jdk/pull/20251#discussion_r1684357333
PR Review Comment: https://git.openjdk.org/jdk/pull/20251#discussion_r1684360034
PR Review Comment: https://git.openjdk.org/jdk/pull/20251#discussion_r1684361244