fill and try_fill methods: improve documentation; add links

Author: dhardy

src/lib.rs

@@ -482,13 +482,16 @@ pub trait Rng {
         Ok(self.fill_bytes(dest))
     }
 
-    /// Fill `dest` entirely with random data.
-    /// 
-    /// This method provides a convenient way to fill a slice with random data.
+    /// Fill `dest` entirely with random data, where `dest` is any slice over
+    /// primitive integers (`i8`, `i16`, `u32`, etc.).
     /// 
     /// On big-endian platforms this performs byte-swapping to ensure
     /// portability of results from reproducible generators.
     /// 
+    /// This uses [`fill_bytes`] internally which may handle some RNG errors
+    /// implicitly (e.g. waiting if the OS generator is not ready), but panics
+    /// on other errors. See also [`try_fill`] which returns errors.
+    /// 
     /// # Example
     /// 
     /// ```rust
@@ -498,21 +501,23 @@ pub trait Rng {
     /// thread_rng().try_fill(&mut arr[..]);
     /// ```
     /// 
-    /// [`ErrorKind`]: enum.ErrorKind.html
+    /// [`fill_bytes`]: trait.Rng.html#method.fill_bytes
+    /// [`try_fill`]: trait.Rng.html#method.try_fill
     fn fill<T: AsByteSliceMut + ?Sized>(&mut self, dest: &mut T) where Self: Sized {
         self.fill_bytes(dest.as_byte_slice_mut());
         dest.to_le();
     }
 
-    /// Fill `dest` entirely with random data.
-    /// 
-    /// This method provides a convenient way to fill a slice with random data.
+    /// Fill `dest` entirely with random data, where `dest` is any slice over
+    /// primitive integers (`i8`, `i16`, `u32`, etc.).
     /// 
     /// On big-endian platforms this performs byte-swapping to ensure
     /// portability of results from reproducible generators.
     /// 
-    /// Errors are forwarded from their source. In some cases errors may be
-    /// resolvable; see [`ErrorKind`] and documentation for the RNG in use.
+    /// This uses [`try_fill_bytes`] internally and forwards all RNG errors. In
+    /// some cases errors may be resolvable; see [`ErrorKind`] and
+    /// documentation for the RNG in use. If you do not plan to handle these
+    /// errors you may prefer to use [`fill`].
     /// 
     /// # Example
     /// 
@@ -530,6 +535,8 @@ pub trait Rng {
     /// ```
     /// 
     /// [`ErrorKind`]: enum.ErrorKind.html
+    /// [`try_fill_bytes`]: trait.Rng.html#method.try_fill_bytes
+    /// [`fill`]: trait.Rng.html#method.fill
     fn try_fill<T: AsByteSliceMut + ?Sized>(&mut self, dest: &mut T) -> Result<(), Error> where Self: Sized {
         self.try_fill_bytes(dest.as_byte_slice_mut())?;
         dest.to_le();
@@ -756,6 +763,11 @@ impl<R: ?Sized> Rng for Box<R> where R: Rng {
 }
 
 /// Trait for casting types to byte slices
+/// 
+/// This is used by the [`fill`] and [`try_fill`] methods.
+/// 
+/// [`fill`]: trait.Rng.html#method.fill
+/// [`try_fill`]: trait.Rng.html#method.try_fill
 pub trait AsByteSliceMut {
     /// Return a mutable reference to self as a byte slice
     fn as_byte_slice_mut<'a>(&'a mut self) -> &'a mut [u8];