Merge pull request #312 from dhardy/trait-guide

Add trait implementation guidance

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:

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)]