Improve consistency of derive(Byte*) documentation
#2306
Conversation
This edit brings the structure of these docs in line with that used for our other derives.
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## v0.8.x #2306 +/- ##
=======================================
Coverage 87.46% 87.46%
=======================================
Files 16 16
Lines 6134 6136 +2
=======================================
+ Hits 5365 5367 +2
Misses 769 769 ☔ View full report in Codecov by Sentry. |
| /// The standard library's [`derive(Hash)`][derive@Hash] produces hashes by | ||
| /// individually hashing each field and combining the results. Instead, the | ||
| /// implementations of [`Hash::hash()`] and [`Hash::hash_slice()`] generated by | ||
| /// `derive(ByteHash)` convert the entirey of `self` to a byte slice and hashes | ||
| /// it in a single call to [`Hasher::write()`]. |
There was a problem hiding this comment.
Maybe mention something about how this is often faster or easier to optimize or something to that effect? After all, that's the only reason you'd use this derive. Currently the only mention of optimization or performance in this doc comment is in the summary sentence.
There was a problem hiding this comment.
The "only mention" being in the summary sentence is fairly prominent positioning. I'm hesitant to over-promise here, because this derive isn't necessarily a performance slam dunk. For example, comparing two u64s for equality is likely to optimize better than casting them to slices of dynamic length and comparing them byte-by-byte. I'm really not sure where the inflection point is.
For that reason, I think the honest thing to do is to explain the mechanics, but not make specific promises about performance.
| /// The standard library's [`derive(Eq, PartialEq)`][derive@PartialEq] computes | ||
| /// equality by individually comparing each field. Instead, the implementation | ||
| /// of [`PartialEq::eq`] emitted by `derive(ByteHash)` converts the entirey of | ||
| /// `self` and `other` to byte slices and compares those slices for equality. |
There was a problem hiding this comment.
Same here re: mentioning performance
This edit brings the structure of these docs in line with that used for our other derives.