diff --git a/rand-core/src/lib.rs b/rand-core/src/lib.rs index e998d1a368a..1c997d50c14 100644 --- a/rand-core/src/lib.rs +++ b/rand-core/src/lib.rs @@ -81,6 +81,19 @@ pub mod le; /// in this trait directly, then use the helper functions from the [`impls`] /// module to implement the other methods. /// +/// It is recommended that implementations also implement: +/// +/// - `Debug` with a custom implementation which *does not* print any internal +/// state (at least, `CryptoRng`s should not risk leaking state through Debug) +/// - `Serialize` and `Deserialize` (from Serde), preferably making Serde +/// support optional at the crate level in PRNG libs +/// - `Clone` if, and only if, the clone will have identical output to the +/// original (i.e. all deterministic PRNGs but not external generators) +/// - *never* implement `Copy` (accidental copies may cause repeated values) +/// - also *do not* implement `Default`, but instead implement `SeedableRng` +/// thus allowing use of `rand::NewRng` (which is automatically implemented) +/// - `Eq` and `PartialEq` could be implemented, but are probably not useful +/// /// # Example /// /// A simple example, obviously not generating very *random* output: diff --git a/src/thread_rng.rs b/src/thread_rng.rs index fb15f07118f..87ec8b489ad 100644 --- a/src/thread_rng.rs +++ b/src/thread_rng.rs @@ -45,7 +45,8 @@ use reseeding::ReseedingRng; const THREAD_RNG_RESEED_THRESHOLD: u64 = 32*1024*1024; // 32 MiB /// The type returned by [`thread_rng`], essentially just a reference to the -/// PRNG in thread-local memory. +/// PRNG in thread-local memory. Cloning this handle just produces a new +/// reference to the same thread-local generator. /// /// [`thread_rng`]: fn.thread_rng.html #[derive(Clone, Debug)]