openpgp: Improve documentation for crypto::random.

  - See #474.

1 files changed, 8 insertions, 0 deletions

diff --git a/openpgp/src/crypto/backend/nettle.rs b/openpgp/src/crypto/backend/nettle.rs
index 8f9fdeb1..724449f9 100644
--- a/openpgp/src/crypto/backend/nettle.rs
+++ b/openpgp/src/crypto/backend/nettle.rs
@@ -9,6 +9,14 @@ pub mod hash;
 pub mod symmetric;
 
 /// Fills the given buffer with random data.
+///
+/// Fills the given buffer with random data produced by a
+/// cryptographically secure pseudorandom number generator (CSPRNG).
+/// The output may be used as session keys or to derive long-term
+/// cryptographic keys from.  However, to create session keys,
+/// consider using [`SessionKey::new`].
+///
+///   [`SessionKey::new`]: struct.SessionKey.html#method.new
 pub fn random<B: AsMut<[u8]>>(mut buf: B) {
     Yarrow::default().random(buf.as_mut());
 }