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/list.rs

@@ -1,3 +1,8 @@
+/// List mode implementation.
+///
+/// This module provides the functionality to list stored items with customizable
+/// formatting, filtering by tags, and support for different output formats
+/// including table, JSON, and YAML.
 use crate::config;
 use crate::services::item_service::ItemService;
 use crate::services::types::ItemWithMeta;
@@ -10,21 +15,68 @@ use serde::{Deserialize, Serialize};
 use serde_json;
 use serde_yaml;
 
+/// Structure representing a list item for structured output formats.
+///
+/// This struct holds all the information needed to serialize an item for JSON or
+/// YAML output in list mode.
 #[derive(Serialize, Deserialize)]
 struct ListItem {
+    /// Item ID.
+    ///
+    /// The unique identifier for the item.
     id: Option<i64>,
+    /// Timestamp.
+    ///
+    /// The formatted timestamp string for the item.
     time: String,
+    /// Size in bytes.
+    ///
+    /// The raw size of the item content.
     size: Option<u64>,
+    /// Formatted size.
+    ///
+    /// Human-readable size string.
     size_formatted: String,
+    /// Compression type.
+    ///
+    /// The compression algorithm used for the item.
     compression: String,
+    /// File size in bytes.
+    ///
+    /// The size of the stored file on disk.
     file_size: Option<u64>,
+    /// Formatted file size.
+    ///
+    /// Human-readable file size string.
     file_size_formatted: String,
+    /// File path.
+    ///
+    /// The full path to the item's storage file.
     file_path: String,
+    /// Tags.
+    ///
+    /// Vector of tag names associated with the item.
     tags: Vec<String>,
+    /// Metadata.
+    ///
+    /// HashMap of metadata key-value pairs.
     meta: std::collections::HashMap<String, String>,
 }
 
-// Helper function to apply color to a cell
+// Helper function to apply color to a cell.
+///
+/// This function converts the configuration color to a comfy-table Color and
+/// applies it to the cell as foreground or background color.
+///
+/// # Arguments
+///
+/// * `cell` - The cell to modify.
+/// * `color` - The color from configuration to apply.
+/// * `is_foreground` - True for foreground color, false for background.
+///
+/// # Returns
+///
+/// The modified cell with color applied.
 fn apply_color(mut cell: Cell, color: &crate::config::TableColor, is_foreground: bool) -> Cell {
     use crate::config::TableColor::*;
     use comfy_table::Color;
@@ -57,7 +109,19 @@ fn apply_color(mut cell: Cell, color: &crate::config::TableColor, is_foreground:
     cell
 }
 
-// Helper function to apply attribute to a cell
+// Helper function to apply attribute to a cell.
+///
+/// This function applies a single table attribute to the cell based on the
+/// configuration attribute type.
+///
+/// # Arguments
+///
+/// * `cell` - The cell to modify.
+/// * `attribute` - The attribute from configuration to apply.
+///
+/// # Returns
+///
+/// The modified cell with attribute applied.
 fn apply_attribute(mut cell: Cell, attribute: &crate::config::TableAttribute) -> Cell {
     use crate::config::TableAttribute::*;
     use comfy_table::Attribute;
@@ -77,6 +141,23 @@ fn apply_attribute(mut cell: Cell, attribute: &crate::config::TableAttribute) ->
     cell
 }
 
+/// Main list mode function.
+///
+/// This function handles the listing of items based on tags, applying formatting
+/// and output options from settings. It supports table, JSON, and YAML output formats.
+///
+/// # Arguments
+///
+/// * `cmd` - Mutable reference to the Clap command for error handling.
+/// * `settings` - Reference to application settings.
+/// * `ids` - Mutable vector of item IDs (should be empty for list mode).
+/// * `tags` - Reference to vector of tags for filtering.
+/// * `conn` - Mutable reference to database connection.
+/// * `data_path` - Path to the data directory.
+///
+/// # Returns
+///
+/// * `Result<()>` - Success or error if listing fails.
 pub fn mode_list(
     cmd: &mut clap::Command,
     settings: &config::Settings,
@@ -235,6 +316,21 @@ pub fn mode_list(
     Ok(())
 }
 
+/// Shows the list of items in a structured format (JSON or YAML).
+///
+/// This function converts the list of items to the specified structured format
+/// and prints it to stdout.
+///
+/// # Arguments
+///
+/// * `items_with_meta` - Vector of items with metadata to display.
+/// * `data_path` - Path to the data directory for file size calculations.
+/// * `settings` - Reference to application settings.
+/// * `output_format` - The desired output format (JSON or YAML).
+///
+/// # Returns
+///
+/// * `Result<()>` - Success or error if serialization fails.
 fn show_list_structured(
     items_with_meta: Vec<ItemWithMeta>,
     data_path: std::path::PathBuf,