docs: Add Rustdoc comments for info and mcp modules and grep plugin

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

src/modes/info.rs

@@ -13,20 +13,32 @@ use comfy_table::{Cell, Attribute};
 
 /// Displays detailed information about an item or the last item if no ID/tags specified.
 ///
-/// Supports table, JSON, or YAML output formats.
+/// Supports table, JSON, or YAML output formats. Validates input (at most one ID, no mixing IDs/tags).
+/// Uses ItemService to fetch the item and displays via helpers.
 ///
 /// # Arguments
 ///
-/// * `cmd` - Mutable Clap command for error handling.
-/// * `settings` - Application settings.
-/// * `ids` - Mutable vector of item IDs (at most one).
+/// * `cmd` - Mutable Clap command for error handling and exiting on invalid args.
+/// * `settings` - Application settings for output formatting and human-readable sizes.
+/// * `ids` - Mutable vector of item IDs (at most one; cleared if tags used).
 /// * `tags` - Mutable vector of tags (mutually exclusive with IDs).
-/// * `conn` - Mutable database connection.
-/// * `data_path` - Path to data directory.
+/// * `conn` - Mutable database connection for querying items.
+/// * `data_path` - Path to data directory for file metadata.
 ///
 /// # Returns
 ///
-/// `Ok(())` on success, or Result with error.
+/// `Ok(())` on success, or `Err(anyhow::Error)` if item not found or DB query fails.
+///
+/// # Errors
+///
+/// * Clap errors if invalid args (e.g., multiple IDs).
+/// * Anyhow error if no matching item found.
+///
+/// # Examples
+///
+/// ```
+/// mode_info(&mut cmd, &settings, &mut vec![123], &mut vec![], &mut conn, data_path)?;
+/// ```
 pub fn mode_info(
     cmd: &mut Command,
     settings: &config::Settings,
@@ -54,6 +66,22 @@ pub fn mode_info(
 
 #[derive(Debug, Serialize, Deserialize)]
 /// Structured representation of item information for JSON/YAML output.
+///
+/// This struct serializes item details including ID, timestamp, sizes, compression, tags, and metadata
+/// for non-table output formats.
+///
+/// # Fields
+///
+/// * `id` - The unique item ID.
+/// * `timestamp` - Formatted timestamp string.
+/// * `path` - Full file path to the item.
+/// * `stream_size` - Original uncompressed size in bytes (optional).
+/// * `stream_size_formatted` - Human-readable stream size.
+/// * `compression` - Compression type used.
+/// * `file_size` - Compressed file size in bytes (optional).
+/// * `file_size_formatted` - Human-readable file size.
+/// * `tags` - List of associated tags.
+/// * `meta` - Metadata key-value pairs.
 pub struct ItemInfo {
     id: i64,
     timestamp: String,
@@ -67,22 +95,35 @@ pub struct ItemInfo {
     meta: std::collections::HashMap<String, String>,
 }
 
+/// Displays item information in table format or delegates to structured output.
+///
+/// Builds a comfy-table for tabular display or calls structured helper for JSON/YAML.
+/// Handles file size via metadata and formats tags/meta accordingly.
+///
+/// # Arguments
+///
+/// * `item_with_meta` - Item with associated metadata and tags.
+/// * `settings` - Application settings for formatting (e.g., human-readable sizes).
+/// * `data_path` - Path to data directory for calculating compressed file size.
+///
+/// # Returns
+///
+/// `Ok(())` on success, or `Err(anyhow::Error)` if path resolution fails.
+///
+/// # Errors
+///
+/// * Anyhow error if item path cannot be stringified.
+///
+/// # Examples
+///
+/// ```
+/// show_item(item_with_meta, &settings, data_path)?;
+/// ```
 fn show_item(
     item_with_meta: ItemWithMeta,
     settings: &config::Settings,
     data_path: PathBuf,
 ) -> Result<()> {
-    /// Displays item information in table format or delegates to structured output.
-    ///
-    /// # Arguments
-    ///
-    /// * `item_with_meta` - Item with associated metadata and tags.
-    /// * `settings` - Application settings for formatting.
-    /// * `data_path` - Path to data directory for file size calculation.
-    ///
-    /// # Returns
-    ///
-    /// `Ok(())` on success.
     let output_format = crate::modes::common::settings_output_format(settings);
 
     if output_format != OutputFormat::Table {
@@ -157,24 +198,37 @@ fn show_item(
     Ok(())
 }
 
+/// Displays item information in structured JSON or YAML format.
+///
+/// Serializes ItemInfo and prints pretty-formatted output. Handles file metadata for sizes.
+///
+/// # Arguments
+///
+/// * `item_with_meta` - Item with metadata and tags.
+/// * `settings` - Settings for size formatting (human-readable).
+/// * `data_path` - Data path for compressed file size calculation.
+/// * `output_format` - JSON or YAML (Table is unreachable here).
+///
+/// # Returns
+///
+/// `Ok(())` on success, or `Err(anyhow::Error)` if serialization or path fails.
+///
+/// # Errors
+///
+/// * Serde errors during JSON/YAML serialization.
+/// * Anyhow error if file metadata unavailable.
+///
+/// # Examples
+///
+/// ```
+/// show_item_structured(item_with_meta, &settings, data_path, OutputFormat::Json)?;
+/// ```
 fn show_item_structured(
     item_with_meta: ItemWithMeta,
     settings: &config::Settings,
     data_path: PathBuf,
     output_format: OutputFormat,
 ) -> Result<()> {
-    /// Displays item information in structured JSON or YAML format.
-    ///
-    /// # Arguments
-    ///
-    /// * `item_with_meta` - Item with metadata and tags.
-    /// * `settings` - Settings for size formatting.
-    /// * `data_path` - Data path for file size.
-    /// * `output_format` - JSON or YAML.
-    ///
-    /// # Returns
-    ///
-    /// `Ok(())` on success.
     let item_tags: Vec<String> = item_with_meta.tags.iter().map(|t| t.name.clone()).collect();
     let meta_map = item_with_meta.meta_as_map();
     let item = item_with_meta.item;