From 87e6da8f29cb31f8d1f639ab5a837e95e09e8856 Mon Sep 17 00:00:00 2001
From: Tony Arcieri <bascule@gmail.com>
Date: Tue, 16 Dec 2025 18:23:08 -0700
Subject: [PATCH] pbkdf2+scrypt: include README.md in rustdoc

These are the only two crates in this repo which aren't doing this
---
 pbkdf2/README.md  |  4 +++-
 pbkdf2/src/lib.rs | 18 ++++++++----------
 scrypt/README.md  |  3 ++-
 scrypt/src/lib.rs | 26 ++++++++++----------------
 4 files changed, 23 insertions(+), 28 deletions(-)

diff --git a/pbkdf2/README.md b/pbkdf2/README.md
index dbfa82b7..9e572350 100644
--- a/pbkdf2/README.md
+++ b/pbkdf2/README.md
@@ -7,7 +7,8 @@
 [![Project Chat][chat-image]][chat-link]
 [![Build Status][build-image]][build-link]
 
-Pure Rust implementation of the [Password-Based Key Derivation Function v2 (PBKDF2)][1].
+Pure Rust implementation of the [Password-Based Key Derivation Function v2 (PBKDF2)][1] as specified
+in [RFC 2898][2].
 
 ## License
 
@@ -40,3 +41,4 @@ dual licensed as above, without any additional terms or conditions.
 [//]: # (general links)
 
 [1]: https://en.wikipedia.org/wiki/PBKDF2
+[2]: https://datatracker.ietf.org/doc/html/rfc2898
diff --git a/pbkdf2/src/lib.rs b/pbkdf2/src/lib.rs
index df2470c9..dec0b3b1 100644
--- a/pbkdf2/src/lib.rs
+++ b/pbkdf2/src/lib.rs
@@ -1,6 +1,11 @@
-//! This crate implements the PBKDF2 key derivation function as specified
-//! in [RFC 2898](https://tools.ietf.org/html/rfc2898).
-//!
+#![no_std]
+#![doc = include_str!("../README.md")]
+#![cfg_attr(docsrs, feature(doc_cfg))]
+#![doc(
+    html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg",
+    html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg"
+)]
+
 //! # Examples
 //!
 //! PBKDF2 is defined in terms of a keyed pseudo-random function (PRF).
@@ -76,13 +81,6 @@
 //! # }
 //! ```
 
-#![no_std]
-#![cfg_attr(docsrs, feature(doc_cfg))]
-#![doc(
-    html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg",
-    html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg"
-)]
-
 #[cfg(feature = "password-hash")]
 extern crate alloc;
 
diff --git a/scrypt/README.md b/scrypt/README.md
index 072d558e..0eeb6e1e 100644
--- a/scrypt/README.md
+++ b/scrypt/README.md
@@ -7,7 +7,8 @@
 ![Rust Version][rustc-image]
 [![Project Chat][chat-image]][chat-link]
 
-Pure Rust implementation of the [scrypt key derivation function][1].
+Pure Rust implementation of the [scrypt key derivation function][1], a sequential memory hard
+function which can also be used for password hashing.
 
 ## License
 
diff --git a/scrypt/src/lib.rs b/scrypt/src/lib.rs
index 9ff2a117..e95b5459 100644
--- a/scrypt/src/lib.rs
+++ b/scrypt/src/lib.rs
@@ -1,16 +1,21 @@
-//! This crate implements the Scrypt key derivation function as specified
-//! in \[1\].
-//!
+#![no_std]
+#![doc = include_str!("../README.md")]
+#![cfg_attr(docsrs, feature(doc_cfg))]
+#![doc(
+    html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg",
+    html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg"
+)]
+
 //! If you are only using the low-level [`scrypt`] function instead of the
 //! higher-level [`Scrypt`] struct to produce/verify hash strings,
 //! it's recommended to disable default features in your `Cargo.toml`:
 //!
 //! ```toml
 //! [dependencies]
-//! scrypt = { version = "0.2", default-features = false }
+//! scrypt = { version = "0.12", default-features = false }
 //! ```
 //!
-//! # Usage (simple with default params)
+//! # Usage (simple PHC password hash usage with default params)
 //!
 #![cfg_attr(all(feature = "alloc", feature = "getrandom"), doc = "```")]
 #![cfg_attr(not(all(feature = "alloc", feature = "getrandom")), doc = "```ignore")]
@@ -36,17 +41,6 @@
 //! # Ok(())
 //! # }
 //! ```
-//!
-//! # References
-//! \[1\] - [C. Percival. Stronger Key Derivation Via Sequential
-//! Memory-Hard Functions](http://www.tarsnap.com/scrypt/scrypt.pdf)
-
-#![no_std]
-#![cfg_attr(docsrs, feature(doc_cfg))]
-#![doc(
-    html_logo_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg",
-    html_favicon_url = "https://raw.githubusercontent.com/RustCrypto/media/8f1a9894/logo.svg"
-)]
 
 #[macro_use]
 extern crate alloc;