RFR: 8312019: Simplify and modernize java.util.BitSet.equals

[Martin Buchholz]

On Thu, 13 Jul 2023 10:50:30 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Please review this PR to use modern APIs and language features to simplify equals for BitSet. 
> 
> I couldn't see how to refactor hashCode using Arrays utility methods in a way that preserves its specification. So, aside from refactoring its doc comment and annotating it with `@Overrides`, I left it intact.

src/java.base/share/classes/java/util/BitSet.java line 1018:

> 1016: 
> 1017:     /**
> 1018:      * {@return the hash code value for this bit set}

I tried to find the (non-obvious) spec for {@return ...}
Googling led me to the now embarrassingly outdated
https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html
https://www.oracle.com/java/technologies/javase/javadoc-tool.html#javadocdocuments
before finding the "real" well-maintained doc
https://docs.oracle.com/en/java/javase/20/docs/specs/javadoc/doc-comment-spec.html
(and that would benefit from TOC and inline anchors)

Improving these docs might be the most valuable engineering work that javadoc team could do!

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

PR Review Comment: https://git.openjdk.org/jdk/pull/14868#discussion_r1268195287