Add docs on customizing string hashing (#90)

Closes #89.

Author: caspark

src/lib.rs

@@ -123,6 +123,31 @@
 //! Some operations are even slightly more efficient and it consumes less memory.
 //! However, all this is at the costs of a less efficient resolution of symbols.
 //! Note that the symbols generated by the `BufferBackend` are not contiguous.
+//!
+//! ## Customizing String Hashing
+//!
+//! To ensure only one copy of each string is interned, [`StringInterner`] relies on [hashbrown]'s
+//! [hashmap](hashbrown::HashMap), which necessitates choosing a hashing function for hashing the
+//! strings.
+//!
+//! By default, [`StringInterner`] will use hashbrown's [`DefaultHashBuilder`], which should be
+//! appropriate for most users. However, you may customize the hash function via
+//! [`StringInterner`]'s second type parameter:
+//!
+//! ```
+//! use std::hash::RandomState;
+//! use string_interner::{StringInterner, DefaultBackend};
+//!
+//! // create a StringInterner with the default backend but using std's RandomState hasher
+//! let interned_strs: StringInterner<DefaultBackend, RandomState> = StringInterner::new();
+//! ```
+//!
+//! NB: as of hashbrown v0.15.2, the [`DefaultHashBuilder`] is [foldhash's
+//! RandomState](https://docs.rs/foldhash/latest/foldhash/fast/struct.RandomState.html), which
+//! relies on a one-time random initialization of shared global state; if you need stable hashes
+//! then you may wish to use [foldhash's
+//! FixedState](https://docs.rs/foldhash/latest/foldhash/fast/struct.FixedState.html) (or similar)
+//! instead.
 
 extern crate alloc;
 #[cfg(feature = "std")]