Rollup merge of #32091 - dirk:dirk/siphasher-docs-clarification, r=alexcrichton

Clarify documentation of hash::SipHasher

The docs were making assertions/recommendations they shouldn't have. This clarifies them and adds some helpful links.

Fixes #32043.

r? @sfackler

1 files changed, 10 insertions, 8 deletions

diff --git a/src/libcore/hash/sip.rs b/src/libcore/hash/sip.rs
index 722d77a8a11..342071f1b51 100644
--- a/src/libcore/hash/sip.rs
+++ b/src/libcore/hash/sip.rs
@@ -19,15 +19,17 @@ use super::Hasher;
 ///
 /// See: http://131002.net/siphash/
 ///
-/// Consider this as a main "general-purpose" hash for all hashtables: it
-/// runs at good speed (competitive with spooky and city) and permits
-/// strong _keyed_ hashing. Key your hashtables from a strong RNG,
-/// such as `rand::Rng`.
+/// This is currently the default hashing function used by standard library
+/// (eg. `collections::HashMap` uses it by default).
 ///
-/// Although the SipHash algorithm is considered to be cryptographically
-/// strong, this implementation has not been reviewed for such purposes.
-/// As such, all cryptographic uses of this implementation are strongly
-/// discouraged.
+/// SipHash is a general-purpose hashing function: it runs at a good
+/// speed (competitive with Spooky and City) and permits strong _keyed_
+/// hashing. This lets you key your hashtables from a strong RNG, such as
+/// [`rand::os::OsRng`](https://doc.rust-lang.org/rand/rand/os/struct.OsRng.html).
+///
+/// Although the SipHash algorithm is considered to be generally strong,
+/// it is not intended for cryptographic purposes. As such, all
+/// cryptographic uses of this implementation are _strongly discouraged_.
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct SipHasher {
     k0: u64,