docs: add module-level docs to 11 crates

Author: EffortlessSteven

crates/uselesskey-bdd-steps/src/lib.rs

@@ -1,4 +1,8 @@
 #![forbid(unsafe_code)]
+//! Cucumber BDD step definitions for uselesskey integration testing.
+//!
+//! Implements Given/When/Then steps that exercise the full uselesskey API
+//! across all key types, adapters, and negative fixture scenarios.
 
 use cucumber::{World, given, then, when};
 #[cfg(feature = "uk-jwt")]

crates/uselesskey-core-cache/src/lib.rs

@@ -1,5 +1,10 @@
 #![forbid(unsafe_code)]
 #![cfg_attr(not(feature = "std"), no_std)]
+//! Identity-keyed typed cache primitives for uselesskey fixture factories.
+//!
+//! Provides a concurrent, identity-based cache that stores generated cryptographic
+//! artifacts keyed by `(domain, label, spec, variant)` tuples. This avoids
+//! expensive re-generation (especially RSA) across test runs.
 
 extern crate alloc;
 
@@ -8,8 +13,6 @@ use alloc::collections::BTreeMap;
 use alloc::sync::Arc;
 use core::any::Any;
 use core::fmt;
-
-#[cfg(feature = "std")]
 use dashmap::DashMap;
 #[cfg(not(feature = "std"))]
 use spin::Mutex;

crates/uselesskey-core-factory/src/lib.rs

@@ -1,5 +1,10 @@
 #![forbid(unsafe_code)]
 #![cfg_attr(not(feature = "std"), no_std)]
+//! Factory orchestration and cache lookup for uselesskey fixtures.
+//!
+//! Implements the core `Factory` type that manages deterministic derivation,
+//! caching, and artifact generation. Operates in either Random or Deterministic
+//! mode based on seed configuration.
 
 extern crate alloc;
 

crates/uselesskey-core-hash/src/lib.rs

@@ -1,5 +1,9 @@
 #![forbid(unsafe_code)]
 #![cfg_attr(not(feature = "std"), no_std)]
+//! Length-prefixed hashing helpers for deterministic fixture derivation.
+//!
+//! Wraps BLAKE3 to provide collision-resistant, deterministic digests used
+//! throughout the `uselesskey` workspace for seed derivation and artifact identity.
 
 pub use blake3::{Hash, Hasher};
 

crates/uselesskey-core-id/src/lib.rs

@@ -1,5 +1,10 @@
 #![forbid(unsafe_code)]
 #![cfg_attr(not(feature = "std"), no_std)]
+//! Core identity and derivation primitives for uselesskey.
+//!
+//! Defines `ArtifactId` — the `(domain, label, spec_fingerprint, variant,
+//! derivation_version)` tuple that uniquely identifies each generated artifact.
+//! Provides deterministic seed derivation from a master seed and artifact id.
 
 extern crate alloc;
 

crates/uselesskey-core-keypair-material/src/lib.rs

@@ -1,4 +1,9 @@
 #![forbid(unsafe_code)]
+//! PKCS#8 / SPKI key-material helpers shared by key fixture crates.
+//!
+//! Provides the `Pkcs8SpkiKeyMaterial` trait and related types for consistent
+//! access to private (PKCS#8) and public (SPKI) key encodings in PEM and DER
+//! formats, plus corrupt PEM/DER negative fixture support.
 
 use std::fmt;
 use std::sync::Arc;

crates/uselesskey-core-kid/src/lib.rs

@@ -1,4 +1,9 @@
 #![forbid(unsafe_code)]
+//! Deterministic key-id (kid) helpers for uselesskey fixture crates.
+//!
+//! Generates URL-safe base64 key identifiers by hashing public key material
+//! with BLAKE3. The default prefix length (12 bytes / 96 bits) provides
+//! sufficient collision resistance for test fixture scenarios.
 
 use base64::Engine as _;
 use base64::engine::general_purpose::URL_SAFE_NO_PAD;

crates/uselesskey-core-negative/src/lib.rs

@@ -1,5 +1,10 @@
 #![forbid(unsafe_code)]
 #![cfg_attr(not(feature = "std"), no_std)]
+//! Negative fixture builders for PEM/DER corruption.
+//!
+//! Re-exports and extends `uselesskey-core-negative-pem` with DER truncation
+//! and corruption helpers. Used by key-type crates to generate intentionally
+//! broken artifacts for error-handling tests.
 
 extern crate alloc;
 

crates/uselesskey-core-seed/src/lib.rs

@@ -1,5 +1,10 @@
 #![forbid(unsafe_code)]
 #![cfg_attr(not(feature = "std"), no_std)]
+//! Seed parsing and redaction primitives for uselesskey.
+//!
+//! Provides the [`Seed`] type that wraps 32 bytes of entropy used for
+//! deterministic fixture derivation. Implements `Debug` with redaction
+//! to prevent accidental leakage of seed material in logs.
 
 extern crate alloc;
 

crates/uselesskey-feature-grid/src/lib.rs

@@ -1,4 +1,9 @@
 #![forbid(unsafe_code)]
+//! Canonical feature and matrix definitions for uselesskey automation.
+//!
+//! Defines `FeatureSet` entries consumed by `cargo xtask feature-matrix` to
+//! drive the CI feature-combination matrix. Each entry specifies a stable
+//! label and the corresponding Cargo CLI arguments.
 
 /// Canonical matrix entry used by automation.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]