Change:
Part of Here's what needs to be done to close out this issue: needs a stronger summary/explanation distinction. "This structure is zero-sized and does not need construction." is weird. also needs a stronger summary/explanation distinction. It also needs a better explanation of why it exists with an example. needs general improvement, it is the main bit of this module, but its docs feel tossed together and have few examples or coherence. needs more than just a summary line; it needs explanation and examples.
What kind of further documentation are you looking for here?
Better explanations for examples of implementing and and and more docs generally for all three.
There seem to be a lengthy example of BuildHasherDefault in this commit () Also for BuildHasher and there is a healthy amount of documentation as of now. Hasher seems to be really outdated (still lists several Implementors without mentioning they have been deprecated), which I'm looking into right now.
Thanks ! Looks like all that's left is documenting .
I am happy to mentor anyone who wants to tackle this issue.
I volunteer as a tribute :-)
wonderful! If you need any help, please just let me know, as I said above, happy to help you help me (We can do it here or ping me on IRC)
I have more specifics in the main issue above
I'm gonna tackle this one this weekend! (if that's okay with you,

Discussion:
/// A hashable type. /// <del> /// The `H` type parameter is an abstract hash state that is used by the `Hash` /// to compute the hash. </del> <ins> /// Types implementing `Hash` are able to be [`hash`]ed with an instance of /// [`Hasher`]. </ins> /// <del> /// If you are also implementing [`Eq`], there is an additional property that /// is important: </del> <ins> /// ## Implementing `Hash` </ins> /// <del> /// ```text /// k1 == k2 -> hash(k1) == hash(k2) /// ``` /// /// In other words, if two keys are equal, their hashes should also be equal. /// [`HashMap`] and [`HashSet`] both rely on this behavior. </del> <ins> /// You can derive `Hash` with `#[derive(Hash)]` if all fields implement `Hash`. /// The resulting hash will be the combination of the values from calling /// [`hash`] on each field. </ins> /// <del> /// ## Derivable /// /// This trait can be used with `#[derive]` if all fields implement `Hash`. /// When `derive`d, the resulting hash will be the combination of the values /// from calling [`.hash`] on each field. /// /// ## How can I implement `Hash`? </del> <ins> /// ``` /// #[derive(Hash)] /// struct Rustacean { ///     name: String, ///     country: String, /// } /// ``` </ins> /// <del> /// If you need more control over how a value is hashed, you need to implement /// the `Hash` trait: </del> <ins> /// If you need more control over how a value is hashed, you can of course /// implement the `Hash` trait yourself: </ins> /// /// ``` /// use std::hash::{Hash, Hasher};

/// } /// ``` /// <ins> /// ## `Hash` and `Eq` /// /// When implementing both `Hash` and [`Eq`], it is important that the following /// property holds: /// /// ```text /// k1 == k2 -> hash(k1) == hash(k2) /// ``` /// /// In other words, if two keys are equal, their hashes must also be equal. /// [`HashMap`] and [`HashSet`] both rely on this behavior. /// /// Thankfully, you won't need to worry about upholding this property when /// deriving both [`Eq`] and `Hash` with `#[derive(PartialEq, Eq, Hash)]`. /// </ins> /// [`Eq`]: ../../std/cmp/trait.Eq.html <ins> /// [`Hasher`]: trait.Hasher.html </ins> /// [`HashMap`]: ../../std/collections/struct.HashMap.html /// [`HashSet`]: ../../std/collections/struct.HashSet.html <del> /// [`.hash`]: #tymethod.hash </del> <ins> /// [`hash`]: #tymethod.hash </ins> #[stable(feature = "rust1", since = "1.0.0")] pub trait Hash { <del> /// Feeds this value into the state given, updating the hasher as necessary. </del> <ins> /// Feeds this value into the given [`Hasher`]. /// /// # Examples /// /// ``` /// use std::collections::hash_map::DefaultHasher; /// use std::hash::{Hash, Hasher}; /// /// let mut hasher = DefaultHasher::new(); /// 7920.hash(&mut hasher); /// println!("Hash is {:x}!", hasher.finish()); /// ``` /// /// [`Hasher`]: trait.Hasher.html </ins> #[stable(feature = "rust1", since = "1.0.0")] fn hash<H: Hasher>(&self, state: &mut H); <del> /// Feeds a slice of this type into the state provided. </del> <ins> /// Feeds a slice of this type into the given [`Hasher`]. /// /// # Examples /// /// ``` /// use std::collections::hash_map::DefaultHasher; /// use std::hash::{Hash, Hasher}; /// /// let mut hasher = DefaultHasher::new(); /// let numbers = [6, 28, 496, 8128]; /// Hash::hash_slice(&numbers, &mut hasher); /// println!("Hash is {:x}!", hasher.finish()); /// ``` /// /// [`Hasher`]: trait.Hasher.html </ins> #[stable(feature = "hash_slice", since = "1.3.0")] fn hash_slice<H: Hasher>(data: &[Self], state: &mut H) where Self: Sized

} } <del> /// A trait which represents the ability to hash an arbitrary stream of bytes. </del> <ins> /// A trait for hashing an arbitrary stream of bytes. /// /// Instances of `Hasher` usually represent state that is changed while hashing /// data. /// /// `Hasher` provides a fairly basic interface for retrieving the generated hash /// (with [`finish`]), and writing integers as well as slices of bytes into an /// instance (with [`write`] and [`write_u8`] etc.). Most of the time, `Hasher` /// instances are used in conjunction with the [`Hash`] trait. /// /// # Examples /// /// ``` /// use std::collections::hash_map::DefaultHasher; /// use std::hash::Hasher; /// /// let mut hasher = DefaultHasher::new(); /// /// hasher.write_u32(1989); /// hasher.write_u8(11); /// hasher.write_u8(9); /// hasher.write(b"Huh?"); /// /// println!("Hash is {:x}!", hasher.finish()); /// ``` /// /// [`Hash`]: trait.Hash.html /// [`finish`]: #tymethod.finish /// [`write`]: #tymethod.write /// [`write_u8`]: #method.write_u8 </ins> #[stable(feature = "rust1", since = "1.0.0")] pub trait Hasher { /// Completes a round of hashing, producing the output hash generated. <ins> /// /// # Examples /// /// ``` /// use std::collections::hash_map::DefaultHasher; /// use std::hash::Hasher; /// /// let mut hasher = DefaultHasher::new(); /// hasher.write(b"Cool!"); /// /// println!("Hash is {:x}!", hasher.finish()); /// ``` </ins> #[stable(feature = "rust1", since = "1.0.0")] fn finish(&self) -> u64; /// Writes some data into this `Hasher`. <ins> /// /// # Examples /// /// ``` /// use std::collections::hash_map::DefaultHasher; /// use std::hash::Hasher; /// /// let mut hasher = DefaultHasher::new(); /// let data = [0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef]; /// /// hasher.write(&data); /// /// println!("Hash is {:x}!", hasher.finish()); /// ``` </ins> #[stable(feature = "rust1", since = "1.0.0")] fn write(&mut self, bytes: &[u8]); <del> /// Write a single `u8` into this hasher. </del> <ins> /// Writes a single `u8` into this hasher. </ins> #[inline] #[stable(feature = "hasher_write", since = "1.3.0")] fn write_u8(&mut self, i: u8) {

} } <del> /// A `BuildHasher` is typically used as a factory for instances of `Hasher` /// which a `HashMap` can then use to hash keys independently. </del> <ins> /// A trait for creating instances of [`Hasher`]. /// /// A `BuildHasher` is typically used (e.g. by [`HashMap`]) to create /// [`Hasher`]s for each key such that they are hashed independently of one /// another, since [`Hasher`]s contain state. /// /// For each instance of `BuildHasher`, the [`Hasher`]s created by /// [`build_hasher`] should be identical. That is, if the same stream of bytes /// is fed into each hasher, the same output will also be generated. /// /// # Examples /// /// ``` /// use std::collections::hash_map::RandomState; /// use std::hash::{BuildHasher, Hasher}; /// /// let s = RandomState::new(); /// let mut hasher_1 = s.build_hasher(); /// let mut hasher_2 = s.build_hasher(); </ins> /// <del> /// Note that for each instance of `BuildHasher`, the created hashers should be /// identical. That is, if the same stream of bytes is fed into each hasher, the /// same output will also be generated. </del> <ins> /// hasher_1.write_u32(8128); /// hasher_2.write_u32(8128); /// /// assert_eq!(hasher_1.finish(), hasher_2.finish()); /// ``` /// /// [`build_hasher`]: #tymethod.build_hasher /// [`Hasher`]: trait.Hasher.html /// [`HashMap`]: ../../std/collections/struct.HashMap.html </ins> #[stable(since = "1.7.0", feature = "build_hasher")] pub trait BuildHasher { /// Type of the hasher that will be created.

/// Creates a new hasher. /// <ins> /// Each call to `build_hasher` on the same instance should produce identical /// [`Hasher`]s. /// </ins> /// # Examples /// /// ```

/// let s = RandomState::new(); /// let new_s = s.build_hasher(); /// ``` <ins> /// /// [`Hasher`]: trait.Hasher.html </ins> #[stable(since = "1.7.0", feature = "build_hasher")] fn build_hasher(&self) -> Self::Hasher; } <del> /// The `BuildHasherDefault` structure is used in scenarios where one has a /// type that implements [`Hasher`] and [`Default`], but needs that type to /// implement [`BuildHasher`]. </del> <ins> /// Used to create a default [`BuildHasher`] instance for types that implement /// [`Hasher`] and [`Default`]. </ins> /// <del> /// This structure is zero-sized and does not need construction. </del> <ins> /// `BuildHasherDefault<H>` can be used when a type `H` implements [`Hasher`] and /// [`Default`], and you need a corresponding [`BuildHasher`] instance, but none is /// defined. /// /// Any `BuildHasherDefault` is [zero-sized]. It can be created with /// [`default`][method.Default]. When using `BuildHasherDefault` with [`HashMap`] or /// [`HashSet`], this doesn't need to be done, since they implement appropriate /// [`Default`] instances themselves. </ins> /// /// # Examples ///

/// /// [`BuildHasher`]: trait.BuildHasher.html /// [`Default`]: ../default/trait.Default.html <ins> /// [method.default]: #method.default </ins> /// [`Hasher`]: trait.Hasher.html /// [`HashMap`]: ../../std/collections/struct.HashMap.html <ins> /// [`HashSet`]: ../../std/collections/struct.HashSet.html /// [zero-sized]: https://doc.rust-lang.org/nomicon/exotic-sizes.html#zero-sized-types-zsts </ins> #[stable(since = "1.7.0", feature = "build_hasher")] pub struct BuildHasherDefault<H>(marker::PhantomData<H>);