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

[Hannes Wallnöfer]

On Thu, 31 Oct 2024 11:48:27 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.

In the PR description you quote `StringBuilder#append(java.lang.String)` and `ZipEntry#CENHDR` as examples for this problem, but those are both public members. In the current JDK docs, I can only find a [link for the latter][CENHDR]  which is actually working.

[CENHDR]: https://download.java.net/java/early_access/jdk24/docs/api/java.base/java/util/zip/ZipEntry.html#CENHDR

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/LinkTaglet.java line 253:

> 251:             if (refSignature.trim().startsWith("#") &&
> 252:                     ! (utils.isPublic(containing) || utils.isLinkable(containing)) &&
> 253:                     ! (utils.isPrivate(refMem) ||utils.isPackagePrivate(refMem))) {

Shouldn't this take into account whether we are running with -private or -package options? Ideally using utils.isIncluded(Element) would take care of this and give the right answer in all cases, although I haven't tried.

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

PR Comment: https://git.openjdk.org/jdk/pull/21802#issuecomment-2449737202
PR Review Comment: https://git.openjdk.org/jdk/pull/21802#discussion_r1824371918