RFR: 8373243 : EnumSet.spliterator() should specify and document its characteristics [v2]

[Joe Darcy]

On Tue, 9 Dec 2025 01:18:48 GMT, Viktor Klang <vklang at openjdk.org> wrote:

>> Addresses https://bugs.openjdk.org/browse/JDK-8373243 by copying and adapting the specification from https://github.com/openjdk/jdk/blob/master/src/java.base/share/classes/java/util/LinkedHashSet.java#L186-L204
>> 
>> Since EnumSet is sealed and only permits two final classes, the verbiage around "Implementations should document the reporting of additional characteristic values." may be considered to get removed from this PR. Kept, for now, for symmetry reasons.
>
> Viktor Klang has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Removing verbiage around implementations documenting additional characteristics as well as making EnumSet::spliterator() final

src/java.base/share/classes/java/util/EnumSet.java line 505:

> 503:     }
> 504: 
> 505:     /**

Hmm. Okay, the situation with LinkedHashSet is a bit different since it is a subclassable class and has the "talk about properties of the general contract of this method for this class and its subclasses" vs "talk about properties of _this_ particular method in _this_ class."

Since this method in EnumSet is not overridden by the concrete non-visiable subclasses I agree it is fine to add a `final` modifier to the method. Since the method is `final` I think it would be fine to either elevate all the "The Spliterator is X, Y, and Z" is normal specification or to have an `impl*Spec*` tag where the properties are listed out, the distinction being that implSpec is normative rather than just informative like `implNote`. HTH

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

PR Review Comment: https://git.openjdk.org/jdk/pull/28696#discussion_r2600907508