docs: Enhance Rustdoc for CompressionService, StatusService, and MetaPluginExec

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

PLAN.md

@@ -245,15 +245,15 @@ Private helpers (e.g., internal `fn` without `pub`) are not flagged, as they don
 43. **src/services/error.rs** [DONE]
     - `CoreError` enum: Partial variants.
 
-44. **src/services/compression_service.rs**
+44. **src/services/compression_service.rs** [DONE]
     - `CompressionService` struct: Partial.
     - Methods (`new`, `get_item_content`, `stream_item_content`): Partial.
 
-45. **src/services/status_service.rs**
+45. **src/services/status_service.rs** [DONE]
     - `StatusService` struct: Partial.
     - `generate_status()` method: Partial.
 
-46. **src/meta_plugin/exec.rs**
+46. **src/meta_plugin/exec.rs** [DONE]
     - `MetaPluginExec` struct: Partial.
     - `new()` function: Partial.
     - Impl `MetaPlugin` methods: Partial.

src/meta_plugin/exec.rs

@@ -5,6 +5,15 @@ use which::which;
 
 use crate::meta_plugin::{MetaPlugin, MetaPluginResponse, MetaPluginType};
 
+/// External program execution meta plugin.
+///
+/// This plugin executes a specified external command during item save operations,
+/// capturing its output as metadata. It supports piping input data to the command's stdin
+/// and processing stdout. Useful for dynamic metadata generation via shell commands.
+///
+/// # Examples
+///
+/// Configured via options like `command: "date"`, the plugin runs `date` and captures output as metadata.
 pub struct MetaPluginExec {
     pub program: String,
     pub args: Vec<String>,
@@ -18,6 +27,9 @@ pub struct MetaPluginExec {
 }
 
 // Manual Debug implementation because Box<dyn Write> doesn't implement Debug
+/// Custom Debug implementation for MetaPluginExec.
+///
+/// Obfuscates the writer field since Box<dyn Write> does not implement Debug.
 impl std::fmt::Debug for MetaPluginExec {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         f.debug_struct("MetaPluginExec")
@@ -36,6 +48,30 @@ impl std::fmt::Debug for MetaPluginExec {
 
 
 impl MetaPluginExec {
+    /// Creates a new MetaPluginExec instance.
+    ///
+    /// Validates the program availability using `which` and initializes outputs and options.
+    /// The meta_name determines the default output key for captured command output.
+    ///
+    /// # Arguments
+    ///
+    /// * `program` - The executable name or path to run.
+    /// * `args` - Slice of arguments to pass to the program.
+    /// * `meta_name` - Name for the metadata output key.
+    /// * `split_whitespace` - If true, takes the first whitespace-separated word from output; otherwise, trims full output.
+    /// * `_options` - Optional configuration options (currently unused beyond passing through).
+    /// * `outputs` - Optional output mappings to override defaults.
+    ///
+    /// # Returns
+    ///
+    /// * `MetaPluginExec` - New plugin instance, with `supported` set based on program availability.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let plugin = MetaPluginExec::new("date", vec![], "timestamp", false, None, None);
+    /// assert!(plugin.supported); // If 'date' is available
+    /// ```
     pub fn new(
         program: &str, 
         args: Vec<&str>, 
@@ -80,14 +116,45 @@ impl MetaPluginExec {
 }
 
 impl MetaPlugin for MetaPluginExec {
+    /// Checks if the external program is available on the system.
+    ///
+    /// # Returns
+    ///
+    /// * `bool` - True if the program was found via `which`.
     fn is_supported(&self) -> bool {
         self.supported
     }
     
+    /// Indicates if this is an internal (built-in) plugin.
+    ///
+    /// External exec plugins are always non-internal.
+    ///
+    /// # Returns
+    ///
+    /// * `false` - Always false for this plugin type.
     fn is_internal(&self) -> bool {
         false
     }
 
+    /// Initializes the plugin by spawning the external process.
+    ///
+    /// Sets up piped stdin/stdout/stderr for the command. Does not finalize yet.
+    ///
+    /// # Returns
+    ///
+    /// * `MetaPluginResponse` - Empty metadata, not finalized.
+    ///
+    /// # Errors
+    ///
+    /// If spawn fails, returns finalized response with no metadata (logs error).
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut plugin = MetaPluginExec::new("echo", vec!["hello"], "output", false, None, None);
+    /// let response = plugin.initialize();
+    /// assert!(!response.is_finalized);
+    /// ```
     fn initialize(&mut self) -> MetaPluginResponse {
         debug!("META: Initializing program plugin: {:?}", self);
 
@@ -123,6 +190,24 @@ impl MetaPlugin for MetaPluginExec {
         }
     }
 
+    /// Finalizes the plugin by waiting for the process to complete and capturing output.
+    ///
+    /// Processes stdout based on split_whitespace option, adds to metadata if successful.
+    /// Logs stderr and status on failure but does not propagate as error.
+    ///
+    /// # Returns
+    ///
+    /// * `MetaPluginResponse` - Metadata from output (if any), always finalized.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let response = plugin.finalize();
+    /// assert!(response.is_finalized);
+    /// if let Some(meta) = response.metadata.first() {
+    ///     // Contains captured output
+    /// }
+    /// ```
     fn finalize(&mut self) -> MetaPluginResponse {
         debug!("META: Finalizing program plugin");
         let mut metadata = Vec::new();
@@ -180,6 +265,18 @@ impl MetaPlugin for MetaPluginExec {
         }
     }
 
+    /// Updates the plugin by writing data to the process's stdin.
+    ///
+    /// Pipes incoming data (e.g., item content) to the command for processing.
+    /// Logs write errors but continues.
+    ///
+    /// # Arguments
+    ///
+    /// * `data` - Byte slice to write to stdin.
+    ///
+    /// # Returns
+    ///
+    /// * `MetaPluginResponse` - Empty metadata, not finalized.
     fn update(&mut self, data: &[u8]) -> MetaPluginResponse {
         if let Some(ref mut writer) = self.writer {
             if let Err(e) = writer.write_all(data) {
@@ -192,10 +289,22 @@ impl MetaPlugin for MetaPluginExec {
         }
     }
 
+    /// Returns the type of this meta plugin.
+    ///
+    /// # Returns
+    ///
+    /// * `MetaPluginType::Exec` - The exec plugin type.
     fn meta_type(&self) -> MetaPluginType {
         MetaPluginType::Exec
     }
     
+    /// Provides information about the program and its arguments.
+    ///
+    /// Only returns data if the program is supported.
+    ///
+    /// # Returns
+    ///
+    /// * `Option<(&str, Vec<&str>)>` - Tuple of program path and arg slices, or None.
     fn program_info(&self) -> Option<(&str, Vec<&str>)> {
         if self.supported {
             Some((&self.program, self.args.iter().map(|s| s.as_str()).collect()))
@@ -204,27 +313,57 @@ impl MetaPlugin for MetaPluginExec {
         }
     }
     
+    /// Returns an immutable reference to the plugin's outputs.
+    ///
+    /// # Returns
+    ///
+    /// * `&HashMap<String, serde_yaml::Value>` - The outputs map.
     fn outputs(&self) -> &std::collections::HashMap<String, serde_yaml::Value> {
         &self.outputs
     }
     
+    /// Returns a mutable reference to the plugin's outputs.
+    ///
+    /// # Returns
+    ///
+    /// * `&mut HashMap<String, serde_yaml::Value>` - Mutable outputs map.
     fn outputs_mut(&mut self) -> &mut std::collections::HashMap<String, serde_yaml::Value> {
         &mut self.outputs
     }
     
+    /// Returns the default output keys for this plugin.
+    ///
+    /// # Returns
+    ///
+    /// * `Vec<String>` - Vector with the exec type string.
     fn default_outputs(&self) -> Vec<String> {
         vec![self.meta_type().to_string()]
     }
     
     
+    /// Returns an immutable reference to the plugin's options.
+    ///
+    /// # Returns
+    ///
+    /// * `&HashMap<String, serde_yaml::Value>` - The options map.
     fn options(&self) -> &std::collections::HashMap<String, serde_yaml::Value> {
         &self.options
     }
     
+    /// Returns a mutable reference to the plugin's options.
+    ///
+    /// # Returns
+    ///
+    /// * `&mut HashMap<String, serde_yaml::Value>` - Mutable options map.
     fn options_mut(&mut self) -> &mut std::collections::HashMap<String, serde_yaml::Value> {
         &mut self.options
     }
 }
+/// Registers the exec meta plugin with the global registry.
+///
+/// This constructor function is called at module load time using ctor crate.
+/// It parses "command" option for program/args, "split_whitespace" for output processing,
+/// and "name" for metadata key. Falls back to defaults if missing.
 use crate::meta_plugin::register_meta_plugin;
 
 // Register the plugin at module initialization time

src/services/compression_service.rs

@@ -5,6 +5,18 @@ use std::path::PathBuf;
 use std::str::FromStr;
 use anyhow::anyhow;
 
+//// Service for handling compression and decompression of item content.
+///
+/// Provides methods to read compressed item files either fully into memory
+/// or as streaming readers. Supports various compression types via engines.
+/// This service abstracts the underlying compression engines for consistent access.
+///
+/// # Examples
+///
+/// ```
+/// let service = CompressionService::new();
+/// let content = service.get_item_content(path, "gzip")?;
+/// ```
 pub struct CompressionService;
 
 /// Service for handling compression and decompression of item content.
@@ -22,9 +34,11 @@ pub struct CompressionService;
 impl CompressionService {
     /// Creates a new CompressionService instance.
     ///
+    /// This is a simple constructor; no initialization is required beyond the static methods.
+    ///
     /// # Returns
     ///
-    /// A new `CompressionService`.
+    /// * `CompressionService` - A new instance of the service.
     ///
     /// # Examples
     ///
@@ -37,19 +51,22 @@ impl CompressionService {
 
     /// Reads and decompresses the full content of an item file into memory.
     ///
+    /// Loads the entire decompressed content as a byte vector. Suitable for small to medium files.
+    ///
     /// # Arguments
     ///
-    /// * `item_path` - Path to the compressed item file.
+    /// * `item_path` - Path to the compressed item file on disk.
-    /// * `compression` - Compression type string (e.g., "gzip").
+    /// * `compression` - Compression type as string (e.g., "gzip", "lz4"); case-insensitive.
     ///
     /// # Returns
     ///
-    /// * `Result<Vec<u8>, CoreError>` - Decompressed content bytes.
+    /// * `Ok(Vec<u8>)` - The full decompressed content bytes.
+    /// * `Err(CoreError)` - On failure (see errors).
     ///
     /// # Errors
     ///
-    /// * `CoreError::Compression(...)` - If compression type invalid.
+    /// * `CoreError::Compression(String)` - If the compression type string is invalid.
-    /// * `CoreError::Other(...)` - If file open or read fails.
+    /// * `CoreError::Other(anyhow::Error)` - If the file cannot be opened, the engine fails, or reading encounters an I/O error.
     ///
     /// # Examples
     ///
@@ -72,22 +89,23 @@ impl CompressionService {
 
     /// Opens a streaming reader for decompressing item content.
     ///
-    /// For Send compatibility, reads full content into memory and returns a Cursor.
+    /// Due to Send requirements in async contexts, this loads the full content into a Cursor.
-    /// Note: Not suitable for very large files due to memory usage.
+    /// Warning: For very large files, this consumes significant memory; consider alternatives for streaming without loading all data.
     ///
     /// # Arguments
     ///
-    /// * `item_path` - Path to the compressed item file.
+    /// * `item_path` - Path to the compressed item file on disk.
-    /// * `compression` - Compression type string.
+    /// * `compression` - Compression type as string (e.g., "gzip", "lz4"); case-insensitive.
     ///
     /// # Returns
     ///
-    /// * `Result<Box<dyn Read + Send>, CoreError>` - Boxed streaming reader.
+    /// * `Ok(Box<dyn Read + Send>)` - A boxed reader that can be used for streaming decompressed data.
+    /// * `Err(CoreError)` - On failure (see errors).
     ///
     /// # Errors
     ///
-    /// * `CoreError::Compression(...)` - If compression type invalid.
+    /// * `CoreError::Compression(String)` - If the compression type string is invalid.
-    /// * `CoreError::Other(...)` - If file open or read fails.
+    /// * `CoreError::Other(anyhow::Error)` - If the file cannot be opened, the engine fails, or reading encounters an I/O error.
     ///
     /// # Examples
     ///

src/services/status_service.rs

@@ -13,14 +13,23 @@ use std::str::FromStr;
 /// configuration, storage paths, compression engines, metadata plugins,
 /// and filter plugins. It provides a unified interface for status reporting
 /// used by both CLI and server modes.
+///
+/// # Examples
+///
+/// ```
+/// let service = StatusService::new();
+/// let status = service.generate_status(&mut cmd, &settings, data_path, db_path);
+/// ```
 pub struct StatusService;
 
 impl StatusService {
     /// Creates a new `StatusService` instance.
     ///
+    /// No specific initialization is needed; it's a stateless service.
+    ///
     /// # Returns
     ///
-    /// A new `StatusService` instance.
+    /// * `StatusService` - A new instance.
     ///
     /// # Examples
     ///
@@ -35,23 +44,28 @@ impl StatusService {
     ///
     /// Collects data about paths, compression engines, available and configured
     /// meta plugins, and filter plugins. Uses the provided settings to determine
-    /// enabled components.
+    /// enabled components. Handles error reporting via Clap if needed.
     ///
     /// # Arguments
     ///
-    /// * `cmd` - Mutable reference to the Clap command for error reporting.
+    /// * `cmd` - Mutable reference to the Clap command for error reporting (e.g., invalid plugins).
-    /// * `settings` - Application settings containing configuration.
+    /// * `settings` - Application settings containing configuration details like enabled plugins.
-    /// * `data_path` - Path to the data storage directory.
+    /// * `data_path` - Path to the data storage directory for item files.
     /// * `db_path` - Path to the SQLite database file.
     ///
     /// # Returns
     ///
-    /// `StatusInfo` - Structured status information.
+    /// * `StatusInfo` - A structured object containing all status details, including paths, plugins, and config.
+    ///
+    /// # Errors
+    ///
+    /// Exits via Clap error if invalid meta plugin types are configured in settings.
     ///
     /// # Examples
     ///
     /// ```
     /// let status = service.generate_status(&mut cmd, &settings, data_path, db_path);
+    /// assert!(!status.filter_plugins.is_empty());
     /// ```
     pub fn generate_status(
         &self,
@@ -100,9 +114,11 @@ impl StatusService {
 impl Default for StatusService {
     /// Returns the default `StatusService` instance.
     ///
+    /// Delegates to `new()` for consistency.
+    ///
     /// # Returns
     ///
-    /// A new `StatusService`.
+    /// * `StatusService` - A new instance.
     fn default() -> Self {
         Self::new()
     }