From e3f07e9ce5d47a82effb11b2c812afa3209499ba Mon Sep 17 00:00:00 2001
From: Tony Arcieri <bascule@gmail.com>
Date: Sat, 9 May 2026 14:53:34 -0600
Subject: [PATCH] ml-dsa: expand usage docs (#1343)

---
 Cargo.lock            |  2 +-
 ml-dsa/Cargo.toml     |  2 +-
 ml-dsa/src/lib.rs     | 28 +++++++++++++++++++++++-----
 ml-dsa/src/signing.rs |  6 +++---
 4 files changed, 28 insertions(+), 10 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index b8fa2ad..78b71b8 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -815,7 +815,7 @@ checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
 
 [[package]]
 name = "ml-dsa"
-version = "0.1.0-rc.9"
+version = "0.1.0-rc.10"
 dependencies = [
  "const-oid",
  "criterion",
diff --git a/ml-dsa/Cargo.toml b/ml-dsa/Cargo.toml
index 1af9fac..e586baa 100644
--- a/ml-dsa/Cargo.toml
+++ b/ml-dsa/Cargo.toml
@@ -4,7 +4,7 @@ description = """
 Pure Rust implementation of ML-DSA (formerly known as CRYSTALS-Dilithium) as
 described in FIPS-204 (final)
 """
-version = "0.1.0-rc.9"
+version = "0.1.0-rc.10"
 edition = "2024"
 rust-version = "1.85"
 license = "Apache-2.0 OR MIT"
diff --git a/ml-dsa/src/lib.rs b/ml-dsa/src/lib.rs
index bf561f9..c4a4e88 100644
--- a/ml-dsa/src/lib.rs
+++ b/ml-dsa/src/lib.rs
@@ -12,6 +12,19 @@
 
 //! # Usage
 //!
+//! The following types provide the core functionality of this crate, and are all generic around the
+//! [`MlDsaParams`] trait which defines the security level and is one of [`MlDsa44`], [`MlDsa65`],
+//! or [`MlDsa87`]  (with `MlDsa65` recommended as providing the best balance of security and
+//! performance):
+//!
+//! - [`SigningKey`]: secret key capable of generating signatures. Implements the [`KeyInit`],
+//!   [`KeyExport`], [`Keypair`], and [`Signer`] traits, as well as [`Generate`] when the
+//!   `rand_core` feature of this crate is enabled.
+//! - [`VerifyingKey`]: public key associated with a given [`SigningKey`]. Implements the
+//!   [`KeyInit`], [`KeyExport`], and [`Verifier`] traits.
+//! - [`Signature`]: ML-DSA signature generated by a `SigningKey`, and verifiable by a
+//!   `VerifyingKey`. Implements the [`SignatureEncoding`] trait.
+//!
 #![cfg_attr(feature = "getrandom", doc = "```")]
 #![cfg_attr(not(feature = "getrandom"), doc = "```ignore")]
 //! # fn main() -> Result<(), signature::Error> {
@@ -49,7 +62,7 @@ pub use crate::{
     verifying::VerifyingKey,
 };
 pub use common::{self, KeyExport, KeyInit, KeySizeUser};
-pub use signature::{self, Error, Keypair, Signer, Verifier};
+pub use signature::{self, Error, Keypair, SignatureEncoding, Signer, Verifier};
 
 #[cfg(feature = "rand_core")]
 pub use common::Generate;
@@ -137,7 +150,7 @@ impl<P: MlDsaParams> TryInto<EncodedSignature<P>> for Signature<P> {
     }
 }
 
-impl<P: MlDsaParams> signature::SignatureEncoding for Signature<P> {
+impl<P: MlDsaParams> SignatureEncoding for Signature<P> {
     type Repr = EncodedSignature<P>;
 }
 
@@ -189,7 +202,8 @@ impl AsMut<Shake256> for MuBuilder {
     }
 }
 
-/// `MlDsa44` is the parameter set for security category 2.
+/// `MlDsa44` is the parameter set for security category 2, providing the equivalent of 128-bit
+/// symmetric security.
 #[derive(Clone, Copy, Debug, Default, PartialEq)]
 pub struct MlDsa44;
 
@@ -206,7 +220,10 @@ impl ParameterSet for MlDsa44 {
     const TAU: usize = 39;
 }
 
-/// `MlDsa65` is the parameter set for security category 3.
+/// `MlDsa65` is the parameter set for security category 3, providing the equivalent of 192-bit
+/// symmetric security, and is the recommended parameter set.
+///
+/// This set provides the best balance between performance and security.
 #[derive(Clone, Copy, Debug, Default, PartialEq)]
 pub struct MlDsa65;
 
@@ -223,7 +240,8 @@ impl ParameterSet for MlDsa65 {
     const TAU: usize = 49;
 }
 
-/// `MlDsa87` is the parameter set for security category 5.
+/// `MlDsa87` is the parameter set for security category 5, providing the equivalent of 256-bit
+/// symmetric security.
 #[derive(Clone, Copy, Debug, Default, PartialEq)]
 pub struct MlDsa87;
 
diff --git a/ml-dsa/src/signing.rs b/ml-dsa/src/signing.rs
index fc97bd2..895f728 100644
--- a/ml-dsa/src/signing.rs
+++ b/ml-dsa/src/signing.rs
@@ -442,7 +442,7 @@ impl<P: MlDsaParams> ExpandedSigningKey<P> {
 
     /// DEPRECATED: encode the key in a fixed-size byte array.
     ///
-    /// Note that this form is deprecated in practice; prefer to use [`SigningKey:to_seed`].
+    /// Note that this form is deprecated in practice; prefer to use [`SigningKey::to_seed`].
     // Algorithm 24 skEncode
     #[deprecated(since = "0.1.0", note = "use `SigningKey::to_seed` instead")]
     pub fn to_expanded(&self) -> ExpandedSigningKeyBytes<P>
@@ -497,8 +497,8 @@ impl<P: MlDsaParams> DigestSigner<Shake256, Signature<P>> for ExpandedSigningKey
     }
 }
 
-/// The [`signature::KeyPair`] implementation for `ExpandedSigningKey` allows to derive a `VerifyingKey` from
-/// a bare `ExpandedSigningKey` (even in the absence of the original seed).
+/// The [`signature::Keypair`] implementation for [`ExpandedSigningKey`] allows to derive a
+/// [`VerifyingKey`] from a bare `ExpandedSigningKey` (even in the absence of the original seed).
 impl<P: MlDsaParams> signature::Keypair for ExpandedSigningKey<P> {
     type VerifyingKey = VerifyingKey<P>;