From 2f41a0b773c4a650e569d7b661e31b31a82b7abb Mon Sep 17 00:00:00 2001
From: Kristofers Solo <dev@kristofers.xyz>
Date: Wed, 31 Dec 2025 00:09:26 +0200
Subject: [PATCH] docs(cipher-core): add documentation to public traits

Document BlockCipher, InputBlock, and BlockParser with usage examples
and method descriptions. Fix incorrect error message in decrypt() that
referenced "plaintext" instead of "ciphertext".
---
 cipher-core/src/traits/block_cipher.rs | 24 ++++++++++++++++++------
 cipher-core/src/traits/input_block.rs  | 13 +++++++++++++
 2 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/cipher-core/src/traits/block_cipher.rs b/cipher-core/src/traits/block_cipher.rs
index b964de0..75e8c03 100644
--- a/cipher-core/src/traits/block_cipher.rs
+++ b/cipher-core/src/traits/block_cipher.rs
@@ -1,11 +1,23 @@
 use crate::{CipherAction, CipherError, CipherResult, Output};
 
-/// Generic block cipher trait.
+/// Generic block cipher trait for symmetric encryption algorithms.
 ///
-/// Implements the standard encrypt/decrypt interface for block ciphers.
-/// Implementers define `transform_impl` to handle the core algorithm,
-/// while `transform` provides validation and convenience wrappers.
+/// Provides a standard encrypt/decrypt interface for block ciphers like AES and DES.
+/// Implementers define [`transform_impl`](Self::transform_impl) to handle the core algorithm,
+/// while [`transform`](Self::transform) provides block size validation.
+///
+/// # Example
+/// ```ignore
+/// use cipher_core::{BlockCipher, CipherAction};
+///
+/// let cipher = Aes::new(key);
+/// let ciphertext = cipher.encrypt(&plaintext)?;
+/// let decrypted = cipher.decrypt(&ciphertext)?;
+/// ```
 pub trait BlockCipher {
+    /// Returns the block size in bytes for this cipher.
+    ///
+    /// Common values: 8 bytes (DES), 16 bytes (AES-128).
     fn block_size(&self) -> usize;
 
     /// Core cipher transformation (must be implemented by concrete types).
@@ -35,7 +47,7 @@ pub trait BlockCipher {
     ///
     /// # Errors
     ///
-    /// Returns `CipherError::InvalidBlockSize` if the plaintext is not exactly `BLOCK_SIZE` bytes.
+    /// Returns `CipherError::InvalidBlockSize` if the plaintext is not exactly `block_size()` bytes.
     fn encrypt(&self, plaintext: &[u8]) -> CipherResult<Output> {
         self.transform(plaintext, CipherAction::Encrypt)
     }
@@ -44,7 +56,7 @@ pub trait BlockCipher {
     ///
     /// # Errors
     ///
-    /// Returns `CipherError::InvalidBlockSize` if the plaintext is not exactly `BLOCK_SIZE` bytes.
+    /// Returns `CipherError::InvalidBlockSize` if the ciphertext is not exactly `block_size()` bytes.
     fn decrypt(&self, ciphertext: &[u8]) -> CipherResult<Output> {
         self.transform(ciphertext, CipherAction::Decrypt)
     }
diff --git a/cipher-core/src/traits/input_block.rs b/cipher-core/src/traits/input_block.rs
index 136ad99..32a8d85 100644
--- a/cipher-core/src/traits/input_block.rs
+++ b/cipher-core/src/traits/input_block.rs
@@ -1,12 +1,25 @@
 use std::ops::{Deref, DerefMut};
 
+/// Trait for fixed-size cipher block types.
+///
+/// Provides a common interface for accessing block data as byte slices,
+/// used by cipher implementations to process input data.
+///
+/// # Implementers
+/// - `Block64` (DES): 8-byte blocks
+/// - `Block128` (AES): 16-byte blocks
 pub trait InputBlock: Sized {
+    /// Block size in bits (e.g., 64 for DES, 128 for AES).
     const BLOCK_SIZE: usize;
 
+    /// Returns the block data as a byte slice.
     fn as_bytes(&self) -> &[u8];
+
+    /// Returns the block data as a mutable byte slice.
     fn as_bytes_mut(&mut self) -> &mut [u8];
 }
 
+/// Wrapper for parsing input blocks with automatic dereferencing.
 #[derive(Debug, Clone)]
 pub struct BlockParser<T: InputBlock>(pub T);