enhance documentation for hash stream interfaces#576
Conversation
There was a problem hiding this comment.
Pull request overview
This PR enhances the public API documentation of the HashStream32/64/128 interfaces by specifying the intended equals(Object) / hashCode() semantics for hash stream implementations.
Changes:
- Expanded the Javadoc for
HashStream32,HashStream64, andHashStream128to describe equality and hashing behavior. - Documented that equality depends on implementation class, underlying hasher equality, and stream state.
- Documented that
hashCode()corresponds to the stream’sgetAsInt()result.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| src/main/java/com/dynatrace/hash4j/hashing/HashStream32.java | Adds detailed Javadoc describing equals/hashCode semantics for 32-bit streams. |
| src/main/java/com/dynatrace/hash4j/hashing/HashStream64.java | Adds the same equals/hashCode semantics documentation for 64-bit streams. |
| src/main/java/com/dynatrace/hash4j/hashing/HashStream128.java | Adds the same equals/hashCode semantics documentation for 128-bit streams. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| * <p>Implementations override {@link Object#equals(Object)} and {@link Object#hashCode()}. Two hash | ||
| * streams are considered equal if they are of the same class, have equal hashers (as defined by the | ||
| * hasher's {@code equals} method), and have the same state. {@link Object#hashCode()} returns the | ||
| * same value as {@link #getAsInt()}. |
There was a problem hiding this comment.
The new equals/hashCode contract is based on the stream's current state, but these streams are mutable (put*/reset/setState/copy). As a result, equals/hashCode will change as data is appended or the stream is reset, which makes instances unsafe to use as keys in hash-based collections while being mutated. Consider adding an explicit note/warning about this mutability and collection-usage caveat in this Javadoc block.
| * same value as {@link #getAsInt()}. | |
| * same value as {@link #getAsInt()}. | |
| * | |
| * <p><strong>Warning:</strong> hash streams are mutable. Consequently, operations that modify the | |
| * current stream state, such as appending data or resetting/changing the state, may change the | |
| * result of {@link Object#equals(Object)} and {@link Object#hashCode()}. Therefore, instances | |
| * should not be used as keys in hash-based collections while they are being mutated. |
| * <p>Implementations override {@link Object#equals(Object)} and {@link Object#hashCode()}. Two hash | ||
| * streams are considered equal if they are of the same class, have equal hashers (as defined by the | ||
| * hasher's {@code equals} method), and have the same state. {@link Object#hashCode()} returns the | ||
| * same value as {@link #getAsInt()}. |
There was a problem hiding this comment.
The new equals/hashCode contract is based on the stream's current state, but these streams are mutable (put*/reset/setState/copy). As a result, equals/hashCode will change as data is appended or the stream is reset, which makes instances unsafe to use as keys in hash-based collections while being mutated. Consider adding an explicit note/warning about this mutability and collection-usage caveat in this Javadoc block.
| * same value as {@link #getAsInt()}. | |
| * same value as {@link #getAsInt()}. | |
| * | |
| * <p><strong>Warning:</strong> equality and hash codes are based on the stream's current state, and | |
| * hash streams are mutable. Appending data, resetting the stream, or otherwise changing its state | |
| * will change the results of {@link Object#equals(Object)} and {@link Object#hashCode()}. | |
| * Therefore, a hash stream instance should not be used as a key in hash-based collections while it | |
| * may still be mutated. |
| * <p>Implementations override {@link Object#equals(Object)} and {@link Object#hashCode()}. Two hash | ||
| * streams are considered equal if they are of the same class, have equal hashers (as defined by the | ||
| * hasher's {@code equals} method), and have the same state. {@link Object#hashCode()} returns the | ||
| * same value as {@link #getAsInt()}. |
There was a problem hiding this comment.
The new equals/hashCode contract is based on the stream's current state, but these streams are mutable (put*/reset/setState/copy). As a result, equals/hashCode will change as data is appended or the stream is reset, which makes instances unsafe to use as keys in hash-based collections while being mutated. Consider adding an explicit note/warning about this mutability and collection-usage caveat in this Javadoc block.
| * same value as {@link #getAsInt()}. | |
| * same value as {@link #getAsInt()}. | |
| * | |
| * <p><strong>Warning:</strong> hash streams are mutable. Consequently, the result of | |
| * {@link Object#equals(Object)} and {@link Object#hashCode()} can change when additional data is | |
| * appended or the stream state is otherwise modified. Therefore, instances should not be used as | |
| * keys in hash-based collections while they are being mutated. |
oertl
force-pushed
the
javadoc-improvements
branch
from
d1f2366 to
8c0b6bd
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
oertl
force-pushed
the
javadoc-improvements
branch
from
e96f81b to
f6b42a8
Compare
|
No description provided.