On Thu, 26 Mar 2026 15:15:04 GMT, Alan Bateman <[email protected]> wrote:
>> In #30392, we found out HexFormat is marked as value based class in Javadoc,
>> but they do not have `@ValueBased`.
>>
>>
>> * <p>
>> * This is a <a
>> href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
>> * class; use of identity-sensitive operations (including reference equality
>> * ({@code ==}), identity hash code, or synchronization) on instances of
>> * {@code HexFormat} may have unpredictable results and should be avoided.
>> * The {@code equals} method should be used for comparisons.
>> * <p>
>> * This class is immutable and thread-safe.
>> * <p>
>> * Unless otherwise noted, passing a null argument to any method will cause a
>> * {@link java.lang.NullPointerException NullPointerException} to be thrown.
>> *
>> * @since 17
>> */
>>
>>
>> public final class HexFormat {
>
> src/java.base/share/classes/java/util/HexFormat.java line 124:
>
>> 122: *
>> 123: * <p>
>> 124: * This is a <a
>> href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
>
> It looks like the note on value-based is going into the API note, same thing
> with the normative text about NPE. Doesn't have to be this PR but I think we
> should consider moving the text up so that it appears before the API note
> heading.
I think it should be do in another issue because it affects all of value based
classes, and also the text is not normalized. For example:
HexFormat.java:
* <p>
* This is a <a
href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
* class; use of identity-sensitive operations (including reference equality
* ({@code ==}), identity hash code, or synchronization) on instances of
* {@code HexFormat} may have unpredictable results and should be avoided.
* The {@code equals} method should be used for comparisons.
* <p>
* This class is immutable and thread-safe.
* <p>
Linker.java:
* @implSpec
* Implementations of this interface are immutable, thread-safe and
* <a
href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/30444#discussion_r2998404099
