From fc7342043922176a8d1e9dc9a1eecb6485b32443 Mon Sep 17 00:00:00 2001
From: Tony Arcieri <bascule@gmail.com>
Date: Thu, 30 Oct 2025 20:41:06 -0600
Subject: [PATCH] [WIP] ml-kem: use `kem` traits in docs

Ideally we could get rid of the bespoke traits in `ml-kem` and replace
them with traits from the `kem` crate.

This PR rewrites the usage example to use the `KeyInit` trait for
generating the seed and initializing a `DecapsulationKey`, as well as
retrieving its associated encapsulator.
---
 ml-kem/src/kem.rs |  2 +-
 ml-kem/src/lib.rs | 14 ++++++++++----
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/ml-kem/src/kem.rs b/ml-kem/src/kem.rs
index 229bcfb..2e18806 100644
--- a/ml-kem/src/kem.rs
+++ b/ml-kem/src/kem.rs
@@ -14,7 +14,7 @@ use crate::{Encoded, EncodedSizeUser, Seed};
 use zeroize::{Zeroize, ZeroizeOnDrop};
 
 // Re-export traits from the `kem` crate
-pub use ::kem::{Decapsulate, Encapsulate};
+pub use ::kem::{Decapsulate, Encapsulate, KeyInit, KeySizeUser};
 
 /// A shared key resulting from an ML-KEM transaction
 pub(crate) type SharedKey = B32;
diff --git a/ml-kem/src/lib.rs b/ml-kem/src/lib.rs
index 7100681..3e4d59f 100644
--- a/ml-kem/src/lib.rs
+++ b/ml-kem/src/lib.rs
@@ -21,12 +21,18 @@
 //! computers.
 //!
 //! ```
-//! # use ml_kem::*;
-//! # use ::kem::{Decapsulate, Encapsulate};
-//! let mut rng = rand::rng();
+//! use ml_kem::{
+//!     MlKem768Params,
+//!     kem::{Decapsulate, Encapsulate, KeyInit}
+//! };
+//!
+//! type DecapsulationKey = ml_kem::kem::DecapsulationKey<MlKem768Params>;
 //!
 //! // Generate a (decapsulation key, encapsulation key) pair
-//! let (dk, ek) = MlKem768::generate(&mut rng);
+//! let mut rng = rand::rng();
+//! let seed = DecapsulationKey::generate_key_with_rng(&mut rng);
+//! let dk = DecapsulationKey::new(&seed);
+//! let ek = dk.encapsulator();
 //!
 //! // Encapsulate a shared key to the holder of the decapsulation key, receive the shared
 //! // secret `k_send` and the encapsulated form `ct`.