RFR: 8202617: javadoc generates broken links to undocumented (e.g. private) members [v3]

[Nizar Benalla]

On Thu, 7 Nov 2024 14:44:29 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

>> Please review this patch to prevent links to private and package-private members to be generated.
>> The bug happens when you link to private/package-private members, and javadoc used to generated links to them (assuming they were inherited because the holder is unreachable).
>> 
>> Taking the code path I changed is very rare, as it only used by 4 anchors in 4 classes in all the JDK.
>> 
>> if (refSignature.trim().startsWith("#") &&
>>                     ! (utils.isPublic(containing) || utils.isLinkable(containing))
>> 
>> 
>> The classes that used it are `StringBuilder`/`StringBuffer` with `#append(java.lang.String)` and `ZipEntry`/`ZipOutputStream` with `#CENHDR`
>> 
>> 
>> I've expanded the test to check whether the links are created when they should be.
>> 
>> The generated documentation before and after the change are identical.
>
> Nizar Benalla has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains four additional commits since the last revision:
> 
>  - check if refMem is selected
>  - Merge remote-tracking branch 'upstream/master' into 8202617-javadoc-generates-broken-links-to-undocumented
>  - whitespace
>  - javadoc no longer generates broken links to undocumented fields
>    expand test
>    (C)

I updated the code using the suggestion by Hannes and a small check in the test to make sure the warnings are emitted.
Here is the javadoc output when trying to build Javadoc for `DocumentedClass` and `UndocumentedClass` with the latest patch

Generating ./out1/allpackages-index.html...
Generating ./out1/index-all.html...
test/langtools/jdk/javadoc/doclet/5093723/DocumentedClass.java:26: warning: reference not accessible: UndocumentedClass
  /** {@link #method} */
      ^
test/langtools/jdk/javadoc/doclet/5093723/DocumentedClass.java:28: warning: reference not accessible: UndocumentedClass
  /** {@link #publicMethod} */
      ^
test/langtools/jdk/javadoc/doclet/5093723/DocumentedClass.java:30: warning: reference not accessible: UndocumentedClass
  /** {@link #protectedMethod} */
      ^
test/langtools/jdk/javadoc/doclet/5093723/DocumentedClass.java:32: warning: reference not accessible: UndocumentedClass
  /** {@link #privateMethod} */
      ^
Generating ./out1/search.html...
Generating ./out1/index.html...


Before (in [432ba68](https://github.com/openjdk/jdk/pull/21802/commits/432ba68602b7d5df8abbd918f11e6b9c615823a1)), the output was the following. I didn't notice it was missing a couple of warnings.

Building index for all classes...
Generating ./out1/allpackages-index.html...
Generating ./out1/index-all.html...
test/langtools/jdk/javadoc/doclet/5093723/DocumentedClass.java:28: warning: reference not accessible: UndocumentedClass
  /** {@link #publicMethod} */
      ^
test/langtools/jdk/javadoc/doclet/5093723/DocumentedClass.java:30: warning: reference not accessible: UndocumentedClass
  /** {@link #protectedMethod} */
      ^
Generating ./out1/search.html...


Here is the [Javadoc](https://cr.openjdk.org/~nbenalla/GeneratedDocs/8202617/out1/package-summary.html) after running the `javadoc` tool on `DocumentedClass` and `UndocumentedClass`

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

PR Comment: https://git.openjdk.org/jdk/pull/21802#issuecomment-2462471480