docs: Enhance Rustdoc for CompressionService, StatusService, and MetaPluginExec

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

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