From 594cb730844ebaf1e686de92c295eedd60004afb Mon Sep 17 00:00:00 2001
From: Tony Arcieri <bascule@gmail.com>
Date: Sat, 2 Aug 2025 18:26:08 -0600
Subject: [PATCH] [WIP] aead: add `doc_usage!` macro

Adds a macro which generates the crate usage boilerplate, customized to
a specific crate and example AEAD cipher.

Downstream crates can use it like:

    #![doc = include_str!("../README.md")]
    #![doc = aead::doc_usage!(Aes256Gcm)]
---
 aead/src/doc.rs | 29 +++++++++++++++++++++++++++++
 aead/src/lib.rs |  1 +
 2 files changed, 30 insertions(+)
 create mode 100644 aead/src/doc.rs

diff --git a/aead/src/doc.rs b/aead/src/doc.rs
new file mode 100644
index 000000000..3f90d1a36
--- /dev/null
+++ b/aead/src/doc.rs
@@ -0,0 +1,29 @@
+//! Documentation macros.
+//!
+//! These are used for writing redundant documentation that shows how to use the trait-based
+//! interface with a concrete crate/type.
+
+/// Write the "Usage" section of the toplevel documentation, using the given `$aead` type in
+/// code examples.
+#[doc(hidden)]
+#[macro_export]
+#[rustfmt::skip]
+macro_rules! doc_usage {
+    ($aead:ident) => {
+        concat!(
+            "# Usage\n",
+            "\n",
+            "Simple usage (allocating, no associated data):\n",
+            "\n",
+            "```\n",
+            "use ", env!("CARGO_CRATE_NAME"), "::{\n",
+            "    aead::{Aead, AeadCore, KeyInit, rand_core::OsRng},\n",
+            "    ", stringify!($aead), ", Nonce, Key\n",
+            "};\n",
+            "\n",
+            "// The encryption key can be generated randomly:\n",
+            "let key = ", stringify!($aead), "::generate_key().expect(\"generate key\");\n",
+            "```\n"
+        )
+    };
+}
diff --git a/aead/src/lib.rs b/aead/src/lib.rs
index a1fbc5f84..9b565d75c 100644
--- a/aead/src/lib.rs
+++ b/aead/src/lib.rs
@@ -18,6 +18,7 @@ extern crate alloc;
 
 #[cfg(feature = "dev")]
 pub mod dev;
+mod doc;
 
 pub use crypto_common::{
     Key, KeyInit, KeySizeUser,