docs(primitives): random functions are cryptographically secure (#872)

crates/primitives/src/bits/fixed.rs

@@ -364,7 +364,10 @@ impl<const N: usize> FixedBytes<N> {
         N
     }
 
-    /// Creates a new [`FixedBytes`] with the default non-cryptographic random number generator.
+    /// Creates a new [`FixedBytes`] with the default cryptographic random number generator.
+    ///
+    /// This is `rand::thread_rng` if the "rand" and "std" features are enabled, otherwise
+    /// it uses `getrandom::getrandom`. Both are cryptographically secure.
     #[cfg(feature = "getrandom")]
     #[inline]
     #[track_caller]
@@ -376,8 +379,10 @@ impl<const N: usize> FixedBytes<N> {
         bytes
     }
 
-    /// Tries to create a new [`FixedBytes`] with the default non-cryptographic random number
+    /// Tries to create a new [`FixedBytes`] with the default cryptographic random number
     /// generator.
+    ///
+    /// See [`random`](Self::random) for more details.
     #[cfg(feature = "getrandom")]
     #[inline]
     pub fn try_random() -> Result<Self, getrandom::Error> {
@@ -389,6 +394,8 @@ impl<const N: usize> FixedBytes<N> {
     }
 
     /// Creates a new [`FixedBytes`] with the given random number generator.
+    ///
+    /// See [`random`](Self::random) for more details.
     #[cfg(feature = "rand")]
     #[inline]
     #[doc(alias = "random_using")]
@@ -400,16 +407,20 @@ impl<const N: usize> FixedBytes<N> {
         bytes
     }
 
-    /// Fills this [`FixedBytes`] with the default non-cryptographic random number generator.
+    /// Fills this [`FixedBytes`] with the default cryptographic random number generator.
+    ///
+    /// See [`random`](Self::random) for more details.
     #[cfg(feature = "getrandom")]
     #[inline]
     #[track_caller]
     pub fn randomize(&mut self) {
         self.try_randomize().unwrap_or_else(|e| panic!("failed to fill with random bytes: {e}"));
     }
 
-    /// Tries to fill this [`FixedBytes`] with the default non-cryptographic random number
+    /// Tries to fill this [`FixedBytes`] with the default cryptographic random number
     /// generator.
+    ///
+    /// See [`random`](Self::random) for more details.
     #[inline]
     #[cfg(feature = "getrandom")]
     pub fn try_randomize(&mut self) -> Result<(), getrandom::Error> {

crates/primitives/src/bits/macros.rs

@@ -426,33 +426,42 @@ macro_rules! impl_fb_traits {
 #[cfg(feature = "getrandom")]
 macro_rules! impl_getrandom {
     () => {
-        /// Creates a new fixed byte array with the default non-cryptographic random number
+        /// Creates a new fixed byte array with the default cryptographic random number
         /// generator.
+        ///
+        /// This is `rand::thread_rng` if the "rand" and "std" features are enabled, otherwise
+        /// it uses `getrandom::getrandom`. Both are cryptographically secure.
         #[inline]
         #[track_caller]
         #[cfg_attr(docsrs, doc(cfg(feature = "getrandom")))]
         pub fn random() -> Self {
             Self($crate::FixedBytes::random())
         }
 
-        /// Tries to create a new fixed byte array with the default non-cryptographic random number
+        /// Tries to create a new fixed byte array with the default cryptographic random number
         /// generator.
+        ///
+        /// See [`random`](Self::random) for more details.
         #[inline]
         #[cfg_attr(docsrs, doc(cfg(feature = "getrandom")))]
         pub fn try_random() -> $crate::private::Result<Self, $crate::private::getrandom::Error> {
             $crate::FixedBytes::try_random().map(Self)
         }
 
-        /// Fills this fixed byte array with the default non-cryptographic random number generator.
+        /// Fills this fixed byte array with the default cryptographic random number generator.
+        ///
+        /// See [`random`](Self::random) for more details.
         #[inline]
         #[track_caller]
         #[cfg_attr(docsrs, doc(cfg(feature = "getrandom")))]
         pub fn randomize(&mut self) {
             self.0.randomize();
         }
 
-        /// Tries to fill this fixed byte array with the default non-cryptographic random number
+        /// Tries to fill this fixed byte array with the default cryptographic random number
         /// generator.
+        ///
+        /// See [`random`](Self::random) for more details.
         #[inline]
         #[cfg_attr(docsrs, doc(cfg(feature = "getrandom")))]
         pub fn try_randomize(