Tweak docs

Author: newpavlov

rand_core/src/block.rs

@@ -96,16 +96,15 @@ pub trait CryptoBlockRng: BlockRngCore {}
 /// `BlockRng` has heavily optimized implementations of the [`RngCore`] methods
 /// reading values from the results buffer, as well as
 /// calling [`BlockRngCore::generate`] directly on the output array when
-/// [`fill_bytes`] / [`try_fill_bytes`] is called on a large array. These methods
-/// also handle the bookkeeping of when to generate a new batch of values.
+/// [`fill_bytes`] is called on a large array. These methods also handle
+/// the bookkeeping of when to generate a new batch of values.
 ///
 /// No whole generated `u32` values are thrown away and all values are consumed
 /// in-order. [`next_u32`] simply takes the next available `u32` value.
 /// [`next_u64`] is implemented by combining two `u32` values, least
-/// significant first. [`fill_bytes`] and [`try_fill_bytes`] consume a whole
-/// number of `u32` values, converting each `u32` to a byte slice in
-/// little-endian order. If the requested byte length is not a multiple of 4,
-/// some bytes will be discarded.
+/// significant first. [`fill_bytes`] consume a whole number of `u32` values,
+/// converting each `u32` to a byte slice in little-endian order. If the requested byte
+/// length is not a multiple of 4, some bytes will be discarded.
 ///
 /// See also [`BlockRng64`] which uses `u64` array buffers. Currently there is
 /// no direct support for other buffer types.
@@ -115,7 +114,6 @@ pub trait CryptoBlockRng: BlockRngCore {}
 /// [`next_u32`]: RngCore::next_u32
 /// [`next_u64`]: RngCore::next_u64
 /// [`fill_bytes`]: RngCore::fill_bytes
-/// [`try_fill_bytes`]: RngCore::try_fill_bytes
 #[derive(Clone)]
 #[cfg_attr(feature = "serde1", derive(Serialize, Deserialize))]
 #[cfg_attr(
@@ -272,14 +270,12 @@ impl<R: CryptoBlockRng + BlockRngCore<Item = u32>> CryptoRng for BlockRng<R> {}
 /// then the other half is then consumed, however both [`next_u64`] and
 /// [`fill_bytes`] discard the rest of any half-consumed `u64`s when called.
 ///
-/// [`fill_bytes`] and [`try_fill_bytes`] consume a whole number of `u64`
-/// values. If the requested length is not a multiple of 8, some bytes will be
-/// discarded.
+/// [`fill_bytes`] `] consume a whole number of `u64` values. If the requested length
+/// is not a multiple of 8, some bytes will be discarded.
 ///
 /// [`next_u32`]: RngCore::next_u32
 /// [`next_u64`]: RngCore::next_u64
 /// [`fill_bytes`]: RngCore::fill_bytes
-/// [`try_fill_bytes`]: RngCore::try_fill_bytes
 #[derive(Clone)]
 #[cfg_attr(feature = "serde1", derive(Serialize, Deserialize))]
 pub struct BlockRng64<R: BlockRngCore + ?Sized> {

rand_core/src/lib.rs

@@ -19,9 +19,6 @@
 //! [`SeedableRng`] is an extension trait for construction from fixed seeds and
 //! other random number generators.
 //!
-//! [`Error`] is provided for error-handling. It is safe to use in `no_std`
-//! environments.
-//!
 //! The [`impls`] and [`le`] sub-modules include a few small functions to assist
 //! implementation of [`RngCore`].
 //!
@@ -68,11 +65,6 @@ pub mod le;
 /// [`next_u32`] and [`next_u64`] methods, implementations may discard some
 /// random bits for efficiency.
 ///
-/// The [`try_fill_bytes`] method is a variant of [`fill_bytes`] allowing error
-/// handling; it is not deemed sufficiently useful to add equivalents for
-/// [`next_u32`] or [`next_u64`] since the latter methods are almost always used
-/// with algorithmic generators (PRNGs), which are normally infallible.
-///
 /// Implementers should produce bits uniformly. Pathological RNGs (e.g. always
 /// returning the same value, or never setting certain bits) can break rejection
 /// sampling used by random distributions, and also break other RNGs when
@@ -128,7 +120,6 @@ pub mod le;
 /// ```
 ///
 /// [`rand`]: https://docs.rs/rand
-/// [`try_fill_bytes`]: RngCore::try_fill_bytes
 /// [`fill_bytes`]: RngCore::fill_bytes
 /// [`next_u32`]: RngCore::next_u32
 /// [`next_u64`]: RngCore::next_u64
@@ -151,11 +142,7 @@ pub trait RngCore {
     ///
     /// RNGs must implement at least one method from this trait directly. In
     /// the case this method is not implemented directly, it can be implemented
-    /// via [`impls::fill_bytes_via_next`] or
-    /// via [`RngCore::try_fill_bytes`]; if this generator can
-    /// fail the implementation must choose how best to handle errors here
-    /// (e.g. panic with a descriptive message or log a warning and retry a few
-    /// times).
+    /// via [`impls::fill_bytes_via_next`].
     ///
     /// This method should guarantee that `dest` is entirely filled
     /// with new data, and may panic if this is impossible
@@ -434,6 +421,9 @@ pub trait SeedableRng: Sized {
     /// This method is the recommended way to construct non-deterministic PRNGs
     /// since it is convenient and secure.
     ///
+    /// Note that this method may panic on (extremely unlikely) [`getrandom`] errors.
+    /// If it's not desirable, use the [`try_from_entropy`] method instead.
+    ///
     /// In case the overhead of using [`getrandom`] to seed *many* PRNGs is an
     /// issue, one may prefer to seed from a local PRNG, e.g.
     /// `from_rng(thread_rng()).unwrap()`.
@@ -443,6 +433,7 @@ pub trait SeedableRng: Sized {
     /// If [`getrandom`] is unable to provide secure entropy this method will panic.
     ///
     /// [`getrandom`]: https://docs.rs/getrandom
+    /// [`try_from_entropy`]: SeedableRng::try_from_entropy
     #[cfg(feature = "getrandom")]
     #[cfg_attr(doc_cfg, doc(cfg(feature = "getrandom")))]
     fn from_entropy() -> Self {
@@ -452,10 +443,8 @@ pub trait SeedableRng: Sized {
         }
     }
 
-    /// Creates a new instance of the RNG seeded via [`getrandom`].
-    ///
-    /// This method is the recommended way to construct non-deterministic PRNGs
-    /// since it is convenient and secure.
+    /// Creates a new instance of the RNG seeded via [`getrandom`] without unwrapping
+    /// potential [`getrandom`] errors.
     ///
     /// In case the overhead of using [`getrandom`] to seed *many* PRNGs is an
     /// issue, one may prefer to seed from a local PRNG, e.g.

src/rng.rs

@@ -223,8 +223,6 @@ pub trait Rng: RngCore {
     /// The distribution is expected to be uniform with portable results, but
     /// this cannot be guaranteed for third-party implementations.
     ///
-    /// This is identical to [`try_fill`] except that it panics on error.
-    ///
     /// # Example
     ///
     /// ```
@@ -235,7 +233,6 @@ pub trait Rng: RngCore {
     /// ```
     ///
     /// [`fill_bytes`]: RngCore::fill_bytes
-    /// [`try_fill`]: Rng::try_fill
     fn fill<T: Fill + ?Sized>(&mut self, dest: &mut T) {
         dest.fill(self)
     }