Enhance documentation across multiple modules for clarity and rationale

Author: nusu-github

src/config.rs

@@ -2,6 +2,14 @@ use clap::Parser;
 use image::ImageFormat;
 use std::path::PathBuf;
 
+/// Command-line configuration for the anime segmentation tool.
+///
+/// # Why clap's derive macro
+///
+/// Using clap's derive API provides automatic help generation, type validation,
+/// and ergonomic argument parsing without manual string manipulation. The derive
+/// approach is preferred over the builder API for its compile-time safety and
+/// reduced boilerplate.
 #[derive(Parser, Clone, Debug)]
 #[command(version, about, long_about = None)]
 pub struct Config {
@@ -28,13 +36,26 @@ impl Config {
 }
 
 impl Default for Config {
+    /// Provide a default configuration for testing purposes.
+    ///
+    /// # Why this exists
+    ///
+    /// Tests need valid Config instances without requiring command-line arguments.
+    /// This default implementation provides placeholder values that satisfy the
+    /// type system. Production code uses `Config::new()` which parses real arguments.
     fn default() -> Self {
-        // This is mainly for tests, parse() is the main way to get a config.
-        // We need to provide dummy patterns that are valid for parsing.
         Config::parse_from(["test", "input/**/*", "--model-path", "model.onnx"])
     }
 }
 
+/// Validate that the requested format is supported for writing.
+///
+/// # Why validation at parse time
+///
+/// Failing early during argument parsing provides immediate feedback to users
+/// rather than discovering unsupported formats after potentially expensive processing.
+/// The validation uses the image crate's runtime capability detection, ensuring
+/// we only accept formats that are actually enabled through feature flags.
 fn check_format(s: &str) -> Result<String, String> {
     let supported: Vec<_> = ImageFormat::all()
         .filter(|f| f.writing_enabled())

src/errors.rs

@@ -1,6 +1,14 @@
 use std::path::PathBuf;
 use thiserror::Error;
 
+/// Structured error types for the anime segmentation application.
+///
+/// # Why structured errors
+///
+/// Each variant captures context specific to its error domain (filesystem, image processing,
+/// model operations, etc.), providing detailed diagnostic information without requiring
+/// callers to parse error strings. The thiserror crate generates Display implementations
+/// automatically from format strings, reducing boilerplate while maintaining type safety.
 #[derive(Error, Debug)]
 pub enum AnimeSegError {
     #[error("Configuration error: {message}")]
@@ -35,15 +43,30 @@ pub enum AnimeSegError {
 
 pub type Result<T> = std::result::Result<T, AnimeSegError>;
 
+/// Convert anyhow errors to configuration errors.
+///
+/// # Why this conversion exists
+///
+/// Some dependencies return anyhow::Error which lacks structured error information.
+/// Rather than propagating the generic error type throughout the codebase, we convert
+/// to our domain-specific error type at boundaries. This trade-off prioritizes API
+/// consistency over preserving fine-grained error details for these specific cases.
 impl From<anyhow::Error> for AnimeSegError {
     fn from(err: anyhow::Error) -> Self {
-        // This is a catch-all. Not ideal, but for simplicity.
         AnimeSegError::Configuration {
             message: err.to_string(),
         }
     }
 }
 
+/// Convert I/O errors to filesystem errors.
+///
+/// # Why default values for context
+///
+/// Some I/O errors occur without specific path/operation context. Rather than
+/// requiring all callsites to wrap errors manually, this conversion provides
+/// a fallback. Code that has context should construct AnimeSegError::FileSystem
+/// directly with the specific path and operation.
 impl From<std::io::Error> for AnimeSegError {
     fn from(err: std::io::Error) -> Self {
         Self::FileSystem {
@@ -54,6 +77,7 @@ impl From<std::io::Error> for AnimeSegError {
     }
 }
 
+/// Convert image crate errors to image processing errors.
 impl From<image::ImageError> for AnimeSegError {
     fn from(err: image::ImageError) -> Self {
         Self::ImageProcessing {
@@ -64,6 +88,7 @@ impl From<image::ImageError> for AnimeSegError {
     }
 }
 
+/// Convert ONNX Runtime errors to model errors.
 impl From<ort::Error> for AnimeSegError {
     fn from(err: ort::Error) -> Self {
         Self::Model {
@@ -73,6 +98,13 @@ impl From<ort::Error> for AnimeSegError {
     }
 }
 
+/// Convert ndarray shape errors to model errors.
+///
+/// # Why model error category
+///
+/// Shape errors occur during tensor operations which are part of model inference,
+/// so they're categorized as model errors rather than a separate tensor error type.
+/// This keeps the error hierarchy flat and focused on user-facing error domains.
 impl From<ndarray::ShapeError> for AnimeSegError {
     fn from(err: ndarray::ShapeError) -> Self {
         Self::Model {

src/lib.rs

@@ -24,12 +24,6 @@ pub use traits::*;
 /// "input/**/*.jpg", we want "input/sub/file.jpg" to become "output/sub/file.jpg",
 /// not "output/input/sub/file.jpg". This function extracts "input" as the base
 /// to enable proper relative path computation.
-///
-/// # Examples
-///
-/// - `"input/**/*.jpg"` → `"input"`
-/// - `"a/b/**/*"` → `"a/b"`
-/// - `"*.jpg"` → `"."`
 fn extract_base_directory(pattern: &str) -> PathBuf {
     let wildcard_pos = pattern.find(['*', '?', '[']).unwrap_or(pattern.len());
 
@@ -49,28 +43,28 @@ fn extract_base_directory(pattern: &str) -> PathBuf {
     }
 }
 
-/// Simple parallel image processor using Rayon for single-machine batch processing.
+/// Batch image processor using trait-based model abstraction.
 ///
-/// This processor is generic over any type implementing `ImageSegmentationModel`,
-/// allowing different model backends (ONNX, TensorRT, etc.) to be used with the
-/// same processing logic. Uses Rayon for straightforward parallel processing without
-/// the complexity of queues or distributed architecture.
+/// Generic over any type implementing `ImageSegmentationModel`, allowing different
+/// model backends to be used with the same processing logic. Processes images
+/// sequentially to maintain simplicity and avoid resource contention with GPU inference.
 pub struct ImageProcessor<M: ImageSegmentationModel> {
     model: M,
     config: Config,
 }
 
 impl<M: ImageSegmentationModel> ImageProcessor<M> {
-    /// Create a new image processor with the given model and configuration.
     pub fn new(model: M, config: Config) -> Self {
         Self { model, config }
     }
 
     /// Process all images matching the input pattern and save results to output directory.
     ///
-    /// This method orchestrates the entire processing workflow: collecting image files,
-    /// creating output directories, processing each image with progress tracking, and
-    /// handling errors gracefully without stopping the entire batch.
+    /// # Error handling strategy
+    ///
+    /// Individual image failures are logged but do not stop the entire batch. This design
+    /// prioritizes completing as much work as possible rather than failing fast, which is
+    /// appropriate for batch processing where partial results are valuable.
     pub fn process_directory(&mut self) -> Result<()> {
         let input_pattern = &self.config.input_pattern;
         let output_path = self.config.output_dir.clone();
@@ -111,12 +105,9 @@ impl<M: ImageSegmentationModel> ImageProcessor<M> {
     }
 
     /// Collect all valid image files matching the glob pattern.
-    ///
-    /// Only includes files with supported image formats to avoid processing errors later.
     fn collect_image_files(&self, pattern: &str) -> Result<Vec<PathBuf>> {
         let mut image_files = Vec::new();
 
-        // Execute glob pattern and filter for valid image files
         for entry in glob(pattern).map_err(|e| AnimeSegError::ImageProcessing {
             path: pattern.to_string(),
             operation: "glob pattern parsing".to_string(),
@@ -139,9 +130,11 @@ impl<M: ImageSegmentationModel> ImageProcessor<M> {
 
     /// Check if the file has a supported image format that can be read.
     ///
-    /// Uses the `image` crate's format detection to determine support dynamically,
-    /// which allows the set of supported formats to expand automatically when
-    /// enabling additional feature flags.
+    /// # Why dynamic format detection
+    ///
+    /// Using the image crate's format detection allows the set of supported formats
+    /// to expand automatically when enabling additional feature flags, avoiding the
+    /// need to maintain a hardcoded list of extensions.
     pub fn is_supported_image_format(&self, path: &Path) -> bool {
         if let Some(extension) = path.extension().and_then(|ext| ext.to_str()) {
             let format = ImageFormat::from_extension(extension);
@@ -156,9 +149,11 @@ impl<M: ImageSegmentationModel> ImageProcessor<M> {
 
     /// Process a single image: load, segment, and save with preserved directory structure.
     ///
-    /// The output path preserves the relative directory structure from the input pattern's
-    /// base directory. This ensures that hierarchical folder organization is maintained
-    /// in the output, which is essential for batch processing large organized datasets.
+    /// # Why preserve directory structure
+    ///
+    /// Maintaining the relative directory structure from input to output is essential
+    /// for batch processing large organized datasets where folder hierarchy provides
+    /// semantic organization (e.g., by date, category, or project).
     fn process_single_image(&mut self, input_file: &Path, output_dir: &Path) -> Result<()> {
         let img = image::open(input_file).map_err(|e| AnimeSegError::ImageProcessing {
             path: input_file.display().to_string(),
@@ -195,16 +190,18 @@ impl<M: ImageSegmentationModel> ImageProcessor<M> {
         Ok(())
     }
 
-    /// Delegate segmentation to the underlying model implementation.
     fn segment_image(&mut self, img: &DynamicImage) -> Result<DynamicImage> {
         self.model.segment_image(img)
     }
 
     /// Compute the relative path from the input pattern's base directory.
     ///
-    /// This is necessary to reconstruct the directory hierarchy in the output.
-    /// For example, with input pattern "photos/**/*.jpg" and file "photos/2024/jan/pic.jpg",
-    /// this returns "2024/jan/pic.jpg" so the output becomes "output/2024/jan/pic.png".
+    /// # Why this computation is necessary
+    ///
+    /// To reconstruct the directory hierarchy in the output while avoiding duplication
+    /// of the base directory. For example, with pattern "photos/**/*.jpg" and file
+    /// "photos/2024/jan/pic.jpg", this returns "2024/jan/pic.jpg" so the output becomes
+    /// "output/2024/jan/pic.png" rather than "output/photos/2024/jan/pic.png".
     pub fn get_relative_path(&self, input_file: &Path) -> Result<PathBuf> {
         let base_dir = extract_base_directory(&self.config.input_pattern);
         input_file
@@ -224,7 +221,9 @@ impl<M: ImageSegmentationModel> ImageProcessor<M> {
 impl ImageProcessor<Model> {
     /// Convenience constructor that creates an ONNX-based image processor.
     ///
-    /// This provides a simpler API for the common case of using the default ONNX model
+    /// # Why this exists
+    ///
+    /// Provides a simpler API for the common case of using the default ONNX model
     /// implementation, avoiding the need to construct the Model separately.
     pub fn with_onnx_model(config: Config) -> Result<Self> {
         let model = Model::new(&config.model_path)?;

src/main.rs

@@ -1,5 +1,13 @@
 use anime_seg_rs::{Config, ImageProcessor, Result};
 
+/// Entry point for the anime segmentation CLI tool.
+///
+/// # Why this is minimal
+///
+/// Following the thin main principle: main.rs only handles program initialization
+/// and delegates all business logic to the library. This design keeps the binary
+/// target separate from the library crate, enabling the library to be used as a
+/// dependency by other projects without pulling in CLI-specific concerns.
 fn main() -> Result<()> {
     let config = Config::new();