docs: Add rustdoc to all files, document arguments and returns

Co-authored-by: aider (openai/andrew/openrouter/sonoma-sky-alpha) <aider@aider.chat>

src/modes/diff.rs

@@ -1,3 +1,7 @@
+/// Diff mode implementation.
+///
+/// This module provides functionality for comparing two items and displaying their
+/// differences using external diff tools.
 use anyhow::{Context, Result};
 use clap::Command;
 use std::io::Read;
@@ -6,23 +10,16 @@ use crate::config;
 use crate::services::item_service::ItemService;
 use log::debug;
 
-fn validate_diff_args(cmd: &mut Command, ids: &Vec<i64>, tags: &Vec<String>) -> anyhow::Result<()> {
-    if !tags.is_empty() {
-        return Err(anyhow::anyhow!("Tags are not supported with --diff. Please provide exactly two IDs."));
-    }
-    if ids.len() != 2 {
-        return Err(anyhow::anyhow!("You must supply exactly two IDs when using --diff."));
-    }
-    Ok(())
-}
-
-/// Validates the diff arguments and exits with error if invalid
+/// Validates diff arguments and exits with error if invalid.
+///
+/// This function checks that exactly two item IDs are provided and no tags are used
+/// with the diff mode, exiting with an appropriate error message if validation fails.
 ///
 /// # Arguments
 ///
-/// * `cmd` - Command instance for error reporting
-/// * `ids` - Vector of item IDs
-/// * `tags` - Vector of tags (should be empty for diff mode)
+/// * `cmd` - Command instance for error reporting.
+/// * `ids` - Vector of item IDs.
+/// * `tags` - Vector of tags (should be empty for diff mode).
 fn validate_diff_args(cmd: &mut Command, ids: &Vec<i64>, tags: &Vec<String>) {
     if !tags.is_empty() {
         cmd.error(
@@ -40,17 +37,44 @@ fn validate_diff_args(cmd: &mut Command, ids: &Vec<i64>, tags: &Vec<String>) {
     }
 }
 
-/// Fetches and validates items from the database for diff operation
+/// Validates the diff arguments and returns a Result if valid.
+///
+/// This function performs the same validation as `validate_diff_args` but returns
+/// an error instead of exiting, allowing for programmatic handling.
 ///
 /// # Arguments
 ///
-/// * `conn` - Mutable reference to the database connection
-/// * `ids` - Vector of item IDs to fetch
-/// * `item_service` - Reference to the item service for validation
+/// * `cmd` - Command instance for error reporting.
+/// * `ids` - Vector of item IDs to fetch.
+/// * `tags` - Vector of tags (should be empty for diff mode).
 ///
 /// # Returns
 ///
-/// * `Result<(ItemWithMeta, ItemWithMeta)>` - Tuple of items with metadata or error
+/// * `anyhow::Result<()>` - Ok if valid, Err with error message if invalid.
+fn validate_diff_args(cmd: &mut Command, ids: &Vec<i64>, tags: &Vec<String>) -> anyhow::Result<()> {
+    if !tags.is_empty() {
+        return Err(anyhow::anyhow!("Tags are not supported with --diff. Please provide exactly two IDs."));
+    }
+    if ids.len() != 2 {
+        return Err(anyhow::anyhow!("You must supply exactly two IDs when using --diff."));
+    }
+    Ok(())
+}
+
+/// Fetches and validates items from the database for diff operation.
+///
+/// This function retrieves two items by their IDs from the database using the
+/// item service, which handles validation, and returns them as a tuple.
+///
+/// # Arguments
+///
+/// * `conn` - Mutable reference to the database connection.
+/// * `ids` - Vector of item IDs to fetch.
+/// * `item_service` - Reference to the item service for validation.
+///
+/// # Returns
+///
+/// * `Result<(ItemWithMeta, ItemWithMeta)>` - Tuple of items with metadata or error.
 fn fetch_and_validate_items(
     conn: &mut rusqlite::Connection,
     ids: &Vec<i64>,
@@ -70,17 +94,20 @@ fn fetch_and_validate_items(
     Ok((item_a, item_b))
 }
 
-/// Sets up file paths and compression for diff operation
+/// Sets up file paths and compression for diff operation.
+///
+/// This function constructs the file paths for the two items and prepares the
+/// compression engines needed for reading their contents.
 ///
 /// # Arguments
 ///
-/// * `item_service` - Reference to the item service
-/// * `item_a` - First item with metadata
-/// * `item_b` - Second item with metadata
+/// * `item_service` - Reference to the item service.
+/// * `item_a` - First item with metadata.
+/// * `item_b` - Second item with metadata.
 ///
 /// # Returns
 ///
-/// * `Result<(PathBuf, PathBuf)>` - Tuple of item file paths or error
+/// * `Result<(PathBuf, PathBuf)>` - Tuple of item file paths or error.
 fn setup_diff_paths_and_compression(
     item_service: &ItemService,
     item_a: &crate::services::types::ItemWithMeta,