On Thu, 13 Jul 2023 10:50:30 GMT, Pavel Rappo <pra...@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
