strong hash: Clarify docs

Reviewed By: iguridi

Differential Revision: D74350789

fbshipit-source-id: 0e592f4b8c24f1b493fcfb829169fdc7f8f7bc04

Author: JakobDegen

gazebo/strong_hash/src/lib.rs

@@ -21,21 +21,15 @@ use crate as strong_hash;
 
 mod impls;
 
-/// `StrongHash`` is a trait that is notionally similar to `std::hash::Hash`,
-/// but carries the implicit expectation that the hash that will be produced
-/// should be as perturbed as possible.
+/// `StrongHash`` is a trait that is notionally similar to `std::hash::Hash`, but carries the
+/// implicit expectation that the hash that will be produced should be as perturbed as possible.
 ///
-/// When implementing `StrongHash` for an object, you should always hash the entire object
-/// and not a subset or a lossy representation of the object unless you are hashing another
-/// cryptographic hash of the object. If you do the latter, a good rule of thumb
-/// is that you should feel comfortable also using that same hash for equality
-/// checks.
+/// `StrongHash` must be implemented such that - when combined with a crypto hasher - the hash value
+/// is suitable to use for equality checks. That means fields must not be omitted and pre-computed
+/// hash values cannot be used if the hasher used for them is weak.
 ///
-/// By default, `StrongHash` is implemented for most rust types that implement
-/// `std::hash::Hash`. including all primitive types, strings, and vectors.
-///
-/// `StrongHash` can be derived on enums and structs if all of their members implement
-/// `StrongHash`. For example:
+/// `StrongHash` can be derived on enums and structs if all of their members implement `StrongHash`.
+/// For example:
 ///
 /// ```ignore
 /// #[derive(StrongHash)]
@@ -46,8 +40,7 @@ mod impls;
 /// }
 /// ```
 ///
-/// `StrongHash` can also be implemented manually similar to std::hash::Hash. For
-/// example:
+/// `StrongHash` can also be implemented manually similar to std::hash::Hash. For example:
 ///
 /// ```ignore
 /// struct MyStruct {