RFR: 8345770: javadoc: API documentation builds are not always reproducible

[Chen Liang]

On Fri, 13 Dec 2024 11:01:51 GMT, Hannes Wallnöfer <hannesw at 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.

Code change makes sense.

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

Marked as reviewed by liach (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/22732#pullrequestreview-2504799473