From 220baa09ade930be45ea2cbe7f9dbcc01ceff220 Mon Sep 17 00:00:00 2001
From: Kristofers Solo <dev@kristofers.xyz>
Date: Wed, 31 Dec 2025 00:26:31 +0200
Subject: [PATCH] docs(cipher-factory): document public API types

Add doc comments to OutputFormat, OperationMode enums and their methods.
Add crate-level documentation describing the factory's purpose.
---
 aes/src/operations/column_mix.rs  |  2 +-
 aes/src/operations/round_key.rs   |  2 +-
 aes/src/operations/row_shift.rs   |  2 +-
 aes/src/operations/sbox_lookup.rs |  2 +-
 cipher-factory/src/lib.rs         |  5 +++++
 cipher-factory/src/operation.rs   |  4 ++++
 cipher-factory/src/output.rs      | 12 ++++++++----
 7 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/aes/src/operations/column_mix.rs b/aes/src/operations/column_mix.rs
index 6806677..f118a0b 100644
--- a/aes/src/operations/column_mix.rs
+++ b/aes/src/operations/column_mix.rs
@@ -1,6 +1,6 @@
 use crate::Block128;
 
-/// Mixes each column using matrix multiplication in GF(2^8) (MixColumns step).
+/// Mixes each column using matrix multiplication in GF(2^8) ([`MixColumns`] step).
 ///
 /// Each column is treated as a polynomial and multiplied by a fixed polynomial
 /// modulo x^4 + 1. This provides diffusion across the rows.
diff --git a/aes/src/operations/round_key.rs b/aes/src/operations/round_key.rs
index eb94b33..0a7f8e4 100644
--- a/aes/src/operations/round_key.rs
+++ b/aes/src/operations/round_key.rs
@@ -1,6 +1,6 @@
 use crate::{Block128, key::Subkey};
 
-/// XORs the state with a round key (AddRoundKey step).
+/// XORs the state with a round key ([`AddRoundKey`] step).
 ///
 /// Each round of AES combines the current state with a derived subkey
 /// using bitwise XOR. This operation is its own inverse.
diff --git a/aes/src/operations/row_shift.rs b/aes/src/operations/row_shift.rs
index 7e61246..0ec1670 100644
--- a/aes/src/operations/row_shift.rs
+++ b/aes/src/operations/row_shift.rs
@@ -1,6 +1,6 @@
 use crate::Block128;
 
-/// Cyclically shifts rows of the state matrix (ShiftRows step).
+/// Cyclically shifts rows of the state matrix ([`ShiftRows`] step).
 ///
 /// Row 0: no shift, Row 1: shift left 1, Row 2: shift left 2, Row 3: shift left 3.
 /// This provides diffusion across the columns.
diff --git a/aes/src/operations/sbox_lookup.rs b/aes/src/operations/sbox_lookup.rs
index 06157f2..7af1486 100644
--- a/aes/src/operations/sbox_lookup.rs
+++ b/aes/src/operations/sbox_lookup.rs
@@ -1,6 +1,6 @@
 use crate::{Block128, sbox::SboxLookup};
 
-/// Substitutes each byte using the AES S-box (SubBytes step).
+/// Substitutes each byte using the AES S-box ([`SubBytes`] step).
 ///
 /// Provides non-linearity by replacing each byte with its S-box lookup value.
 /// The S-box is derived from the multiplicative inverse in GF(2^8).
diff --git a/cipher-factory/src/lib.rs b/cipher-factory/src/lib.rs
index ef98a38..53d942a 100644
--- a/cipher-factory/src/lib.rs
+++ b/cipher-factory/src/lib.rs
@@ -1,3 +1,8 @@
+//! Cipher factory for creating and configuring block ciphers.
+//!
+//! Provides a unified interface for AES and DES encryption/decryption
+//! with configurable output formats.
+
 mod algorithm;
 mod context;
 mod operation;
diff --git a/cipher-factory/src/operation.rs b/cipher-factory/src/operation.rs
index 49716db..3f74f10 100644
--- a/cipher-factory/src/operation.rs
+++ b/cipher-factory/src/operation.rs
@@ -1,14 +1,18 @@
 use std::{convert::Infallible, fmt::Display, str::FromStr};
 
+/// Cipher operation mode - encrypt or decrypt.
 #[cfg_attr(feature = "clap", derive(clap::ValueEnum))]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
 pub enum OperationMode {
+    /// Transform plaintext to ciphertext.
     #[default]
     Encrypt,
+    /// Transform ciphertext to plaintext.
     Decrypt,
 }
 
 impl OperationMode {
+    /// Returns the opposite operation mode.
     #[must_use]
     pub const fn invert(self) -> Self {
         match self {
diff --git a/cipher-factory/src/output.rs b/cipher-factory/src/output.rs
index 7e0de90..58c622b 100644
--- a/cipher-factory/src/output.rs
+++ b/cipher-factory/src/output.rs
@@ -2,21 +2,25 @@ use cipher_core::Output;
 use std::{convert::Infallible, fmt::Display, str::FromStr};
 use strum::EnumIter;
 
+/// Output format for displaying cipher results.
+///
+/// Controls how decrypted data is presented to the user.
 #[cfg_attr(feature = "clap", derive(clap::ValueEnum))]
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Default, EnumIter)]
 pub enum OutputFormat {
-    /// Binary output
+    /// Binary (base-2) representation.
     Binary,
-    /// Octal output
+    /// Octal (base-8) representation.
     Octal,
-    /// Decimal output
+    /// Hexadecimal (base-16) representation.
     #[default]
     Hex,
-    /// Text output (ASCII)
+    /// ASCII text (attempts UTF-8 decoding).
     Text,
 }
 
 impl OutputFormat {
+    /// Formats the cipher output according to this format.
     #[must_use]
     pub fn format(&self, value: &Output) -> String {
         match self {