Docs: Improve docs on util
@@ -28,25 +28,29 @@ use subtle::ConstantTimeEq;
#[must_use]
#[inline(never)]
#[cfg(feature = "safe_api")]
-/// Generate random bytes. Not available in `no_std` context.
+/// Generate random bytes using a CSPRNG. Not available in `no_std` context.
///
/// # About:
/// This function can be used to generate cryptographic keys, salts or other values that rely
-/// on strong randomness. This function fills `dst` with random bytes and the amount of bytes is therefor
-/// implied by the length of `dst`.
+/// on strong randomness. Please note that most keys and other types used throughout orion, implement
+/// their own `generate()` function and it is strongly preffered to use those, compared to `secure_rand_bytes()`.
+///
+/// This uses rand's [OsRng](https://docs.rs/rand/0.6.0/rand/rngs/struct.OsRng.html).
///
-/// This uses rand's [OsRng](https://docs.rs/rand/0.5.5/rand/rngs/struct.OsRng.html).
+/// # Parameters:
+/// - `dst`: Destination buffer for the randomly generated bytes. The amount of bytes to be generated is
+/// implied by the length of `dst`.
///
/// # Exceptions:
/// An exception will be thrown if:
-/// - The `OsRng` fails to initialize or read from its source
-/// - `dst` is empty
+/// - The `OsRng` fails to initialize or read from its source.
+/// - `dst` is empty.
///
/// # Example:
/// ```
/// use orion::util;
///
-/// let mut salt = [0u8; 16];
+/// let mut salt = [0u8; 64];
///
/// util::secure_rand_bytes(&mut salt).unwrap();
/// ```
@@ -69,18 +73,21 @@ pub fn secure_rand_bytes(dst: &mut [u8]) -> Result<(), errors::UnknownCryptoErro
/// Compare two equal length slices, in constant time, using the
/// [subtle](https://crates.io/crates/subtle) crate.
///
+/// # Parameters:
+/// - `a`: The first slice used in the comparison.
+/// - `b`: The second slice used in the comparison.
+///
/// # Exceptions:
/// An exception will be thrown if:
-/// - `a` and `b` do not have the same length
-/// - `a` is not equal to `b`
+/// - `a` and `b` do not have the same length.
+/// - `a` is not equal to `b`.
///
/// # Example:
/// ```
/// use orion::util;
///
/// let mut mac = [0u8; 64];
-///
-/// assert!(util::secure_cmp(&mac, &[0u8; 64]).is_ok());
+/// assert!(util::secure_cmp(&mac, &[0u8; 64]).unwrap());
///
/// util::secure_rand_bytes(&mut mac).unwrap();
/// assert!(util::secure_cmp(&mac, &[0u8; 64]).is_err());
