Re: RFR: 8345770: javadoc: API documentation builds are not always reproducible
On Fri, 13 Dec 2024 11:01:51 GMT, Hannes Wallnöfer 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
Re: RFR: 8345770: javadoc: API documentation builds are not always reproducible
On Fri, 13 Dec 2024 11:01:51 GMT, Hannes Wallnöfer 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.
Great change!
I compared the generated docs before/after the change and the changes are all
in the`class-use` pages, where the qualified name is now used instead.
List of changed files
java.base/java/nio/file/attribute/class-use/AclEntryPermission.html
java.base/java/math/class-use/BigDecimal.html
java.base/java/lang/class-use/Boolean.html
java.base/java/lang/class-use/Character.UnicodeBlock.html
java.desktop/java/awt/class-use/ComponentOrientation.html
java.base/java/util/concurrent/class-use/CountedCompleter.html
java.desktop/java/awt/class-use/Cursor.html
java.datatransfer/java/awt/datatransfer/class-use/DataFlavor.html
java.base/java/net/class-use/DatagramSocket.html
java.base/java/util/concurrent/class-use/ForkJoinTask.html
java.desktop/javax/swing/class-use/JLayer.html
java.base/java/lang/classfile/instruction/LabelTarget.html
jdk.dynalink/jdk/dynalink/linker/class-use/LinkerServices.html
java.base/java/util/concurrent/locks/class-use/Lock.html
java.base/java/lang/invoke/class-use/MethodHandle.html
java.base/java/lang/invoke/class-use/MethodHandles.Lookup.html
java.base/java/lang/class-use/Object.html
java.base/java/util/class-use/Optional.html
java.prefs/java/util/prefs/class-use/Preferences.html
java.base/java/util/concurrent/locks/class-use/ReadWriteLock.html
java.base/java/net/class-use/ServerSocket.html
java.base/java/net/class-use/Socket.html
java.base/java/lang/class-use/String.html
java.base/java/net/class-use/URL.html
java.base/java/util/class-use/UUID.html
java.xml/javax/xml/stream/class-use/XMLEventFactory.html
java.xml/javax/xml/stream/class-use/XMLInputFactory.html
java.xml/javax/xml/stream/class-use/XMLOutputFactory.html
java.xml/javax/xml/xpath/class-use/XPathFactory.html
-
Marked as reviewed by nbenalla (Committer).
PR Review: https://git.openjdk.org/jdk/pull/22732#pullrequestreview-2502133175
RFR: 8345770: javadoc: API documentation builds are not always reproducible
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.
-
Commit messages:
- Remove unused currentTimeElement field
- 8345770: javadoc: API documentation builds are not always reproducible
Changes: https://git.openjdk.org/jdk/pull/22732/files
Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=22732&range=00
Issue: https://bugs.openjdk.org/browse/JDK-8345770
Stats: 42 lines in 13 files changed: 7 ins; 10 del; 25 mod
Patch: https://git.openjdk.org/jdk/pull/22732.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/22732/head:pull/22732
PR: https://git.openjdk.org/jdk/pull/22732
