diff --git a/Cargo.lock b/Cargo.lock
index 502feb56..f3a19e53 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -356,12 +356,40 @@ dependencies = [
  "universal-hash",
 ]
 
+[[package]]
+name = "ppv-lite86"
+version = "0.2.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed0cfbc8191465bed66e1718596ee0b0b35d5ee1f41c5df2189d0fe8bde535ba"
+
 [[package]]
 name = "proc-macro-hack"
 version = "0.5.19"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "dbf0c48bc1d91375ae5c3cd81e3722dff1abcf81a30960240640d223f59fe0e5"
 
+[[package]]
+name = "rand"
+version = "0.8.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2e7573632e6454cf6b99d7aac4ccca54be06da05aca2ef7423d22d27d4d4bcd8"
+dependencies = [
+ "libc",
+ "rand_chacha",
+ "rand_core",
+ "rand_hc",
+]
+
+[[package]]
+name = "rand_chacha"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88"
+dependencies = [
+ "ppv-lite86",
+ "rand_core",
+]
+
 [[package]]
 name = "rand_core"
 version = "0.6.3"
@@ -371,6 +399,15 @@ dependencies = [
  "getrandom",
 ]
 
+[[package]]
+name = "rand_hc"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d51e9f596de227fda2ea6c84607f5558e196eeaf43c986b724ba4fb8fdf497e7"
+dependencies = [
+ "rand_core",
+]
+
 [[package]]
 name = "salsa20"
 version = "0.9.0"
@@ -427,6 +464,7 @@ version = "0.8.0"
 dependencies = [
  "aead",
  "poly1305",
+ "rand",
  "rand_core",
  "salsa20",
  "subtle",
diff --git a/xsalsa20poly1305/Cargo.toml b/xsalsa20poly1305/Cargo.toml
index 3eb1bb43..3d5b253d 100644
--- a/xsalsa20poly1305/Cargo.toml
+++ b/xsalsa20poly1305/Cargo.toml
@@ -29,6 +29,9 @@ alloc = ["aead/alloc"]
 heapless = ["aead/heapless"]
 stream = ["aead/stream"]
 
+[dev-dependencies]
+rand = "0.8.4"
+
 [package.metadata.docs.rs]
 all-features = true
 rustdoc-args = ["--cfg", "docsrs"]
diff --git a/xsalsa20poly1305/src/lib.rs b/xsalsa20poly1305/src/lib.rs
index 9f0a0bba..6de3f862 100644
--- a/xsalsa20poly1305/src/lib.rs
+++ b/xsalsa20poly1305/src/lib.rs
@@ -22,19 +22,20 @@
 //! # Usage
 //!
 //! ```
-//! use xsalsa20poly1305::XSalsa20Poly1305;
-//! use xsalsa20poly1305::aead::{Aead, NewAead, generic_array::GenericArray};
+//! use xsalsa20poly1305::{XSalsa20Poly1305, generate_nonce};
+//! use xsalsa20poly1305::aead::{Aead, NewAead};
+//! use rand::rngs::OsRng;
 //!
-//! let key = GenericArray::from_slice(b"an example very very secret key.");
-//! let cipher = XSalsa20Poly1305::new(key);
+//! // 32-bytes key
+//! let key = XSalsa20Poly1305::generate_key(&mut OsRng::default());
+//! let cipher = XSalsa20Poly1305::new(&key);
 //!
 //! // 24-bytes; unique per message
-//! // Use `xsalsa20poly1305::generate_nonce()` to randomly generate one
-//! let nonce = GenericArray::from_slice(b"extra long unique nonce!");
+//! let nonce = generate_nonce(&mut OsRng::default());
 //!
-//! let ciphertext = cipher.encrypt(nonce, b"plaintext message".as_ref())
+//! let ciphertext = cipher.encrypt(&nonce, b"plaintext message".as_ref())
 //!     .expect("encryption failure!"); // NOTE: handle this error to avoid panics!
-//! let plaintext = cipher.decrypt(nonce, ciphertext.as_ref())
+//! let plaintext = cipher.decrypt(&nonce, ciphertext.as_ref())
 //!     .expect("decryption failure!"); // NOTE: handle this error to avoid panics!
 //!
 //! assert_eq!(&plaintext, b"plaintext message");
@@ -61,23 +62,24 @@
 //! use xsalsa20poly1305::XSalsa20Poly1305;
 //! use xsalsa20poly1305::aead::{AeadInPlace, NewAead, generic_array::GenericArray};
 //! use xsalsa20poly1305::aead::heapless::Vec;
+//! use rand::rngs::OsRng;
 //!
-//! let key = GenericArray::from_slice(b"an example very very secret key.");
-//! let cipher = XSalsa20Poly1305::new(key);
+//! let key = XSalsa20Poly1305::generate_key(&mut OsRng::default());
+//! let cipher = XSalsa20Poly1305::new(&key);
 //!
-//! let nonce = GenericArray::from_slice(b"extra long unique nonce!"); // 24-bytes; unique
+//! let nonce = generate_nonce(&mut OsRng::default());
 //!
 //! let mut buffer: Vec<u8, 128> = Vec::new();
 //! buffer.extend_from_slice(b"plaintext message");
 //!
 //! // Encrypt `buffer` in-place, replacing the plaintext contents with ciphertext
-//! cipher.encrypt_in_place(nonce, b"", &mut buffer).expect("encryption failure!");
+//! cipher.encrypt_in_place(&nonce, b"", &mut buffer).expect("encryption failure!");
 //!
 //! // `buffer` now contains the message ciphertext
 //! assert_ne!(&buffer, b"plaintext message");
 //!
 //! // Decrypt `buffer` in-place, replacing its ciphertext context with the original plaintext
-//! cipher.decrypt_in_place(nonce, b"", &mut buffer).expect("decryption failure!");
+//! cipher.decrypt_in_place(&nonce, b"", &mut buffer).expect("decryption failure!");
 //! assert_eq!(&buffer, b"plaintext message");
 //! # }
 //! ```