[WIP] aead: add doc_usage! macro

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"
+        )
+    };
+}

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,