On Fri, 13 Dec 2024 11:01:51 GMT, Hannes Wallnöfer <hann...@openjdk.org> wrote:

> Please review a fix for a bug that could cause non-reproducible documentation 
> builds and the wrong link label being used in summary pages. 
> 
> We used to rely on field `HtmlConfiguration.currentTypeElement` to decide 
> whether to include the type name in member links generated from `{@link}` or 
> `@see` tags. However, that field was only set by the `ClassWriter` and 
> `ClassUseWriter` classes, but never unset by any other writer class, so 
> effectively it contained the *last* instead of the *current* type element. 
> This resulted in summary pages using non-qualified member links, depending on 
> the last previously executing class writer.
> 
> The fix is to use `HtmlDocletWriter.getCurrentTypeElement()` (previously 
> called `getCurrentPageElement()`) instead. Note that this method returns 
> `null` for `ClassUseWriter`, so it changes the generated documentation for 
> class-use pages. The new behavior is preferable, because class-use pages are 
> primarily about other classes using the class, so links to members of the 
> used class should be qualified by the class name. A good example for this are 
> the links to the `FALSE` and `TRUE` fields in the [class use page for 
> java.lang.Boolean][1] which should include the class name.
> 
> [1]: 
> https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/lang/class-use/Boolean.html#java.lang.constant
> 
> As mentioned above I also renamed `getCurrentPageElement()` method to 
> `getCurrentTypeElement()` and made the doc comments a bit more precise.

This pull request has now been integrated.

Changeset: 4fc43b0b
Author:    Hannes Wallnöfer <hann...@openjdk.org>
URL:       
https://git.openjdk.org/jdk/commit/4fc43b0b49c3d7c4351646f2580860495d8a0d67
Stats:     42 lines in 13 files changed: 7 ins; 10 del; 25 mod

8345770: javadoc: API documentation builds are not always reproducible

Reviewed-by: nbenalla, liach

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

PR: https://git.openjdk.org/jdk/pull/22732

Reply via email to