docs: Add rustdoc comments for functions, structs, and traits

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

src/meta_plugin/mod.rs

@@ -34,50 +34,88 @@ pub use shell_pid::ShellPidMetaPlugin;
 pub use keep_pid::KeepPidMetaPlugin;
 pub use env::EnvMetaPlugin;
 
-/// Represents metadata to be stored
+/// Represents metadata to be stored.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct MetaData {
+    /// The name of the metadata field.
     pub name: String,
+    /// The value of the metadata field.
     pub value: String,
 }
 
-/// Response from meta plugin operations
+/// Response from meta plugin operations.
 #[derive(Debug, Default, Clone, Serialize, Deserialize)]
 pub struct MetaPluginResponse {
+    /// The generated metadata items.
     pub metadata: Vec<MetaData>,
+    /// Indicates if the plugin has finished processing.
     pub is_finalized: bool,
 }
 
-/// Base implementation for meta plugins to reduce boilerplate
+/// Base implementation for meta plugins to reduce boilerplate.
 #[derive(Debug, Clone, Default)]
 pub struct BaseMetaPlugin {
+    /// Output mappings for metadata.
     pub outputs: std::collections::HashMap<String, serde_yaml::Value>,
+    /// Configuration options for the plugin.
     pub options: std::collections::HashMap<String, serde_yaml::Value>,
+    /// Whether the plugin is finalized.
     pub is_finalized: bool,
 }
 
 impl BaseMetaPlugin {
+    /// Creates a new `BaseMetaPlugin`.
+    ///
+    /// # Returns
+    ///
+    /// A new instance of `BaseMetaPlugin`.
     pub fn new() -> Self {
         Self::default()
     }
     
+    /// Returns a reference to the outputs mapping.
+    ///
+    /// # Returns
+    ///
+    /// A reference to the `HashMap` of outputs.
     pub fn outputs(&self) -> &std::collections::HashMap<String, serde_yaml::Value> {
         &self.outputs
     }
     
+    /// Returns a mutable reference to the outputs mapping.
+    ///
+    /// # Returns
+    ///
+    /// A mutable reference to the `HashMap` of outputs.
     pub fn outputs_mut(&mut self) -> &mut std::collections::HashMap<String, serde_yaml::Value> {
         &mut self.outputs
     }
     
+    /// Returns a reference to the options mapping.
+    ///
+    /// # Returns
+    ///
+    /// A reference to the `HashMap` of options.
     pub fn options(&self) -> &std::collections::HashMap<String, serde_yaml::Value> {
         &self.options
     }
     
+    /// Returns a mutable reference to the options mapping.
+    ///
+    /// # Returns
+    ///
+    /// A mutable reference to the `HashMap` of options.
     pub fn options_mut(&mut self) -> &mut std::collections::HashMap<String, serde_yaml::Value> {
         &mut self.options
     }
     
-    /// Helper function to initialize plugin options and outputs
+    /// Helper function to initialize plugin options and outputs.
+    ///
+    /// # Arguments
+    ///
+    /// * `default_outputs` - Slice of default output names.
+    /// * `options` - Optional user-provided options.
+    /// * `outputs` - Optional user-provided outputs.
     pub fn initialize_plugin(
         &mut self,
         default_outputs: &[&str],
@@ -100,24 +138,49 @@ impl BaseMetaPlugin {
 }
 
 impl MetaPlugin for BaseMetaPlugin {
+    /// Returns the type of this meta plugin.
+    ///
+    /// # Returns
+    ///
+    /// `MetaPluginType::Text` (default for base).
     fn meta_type(&self) -> MetaPluginType {
         // This is a base implementation, so we need to return something
         // This might not be used, but we need to satisfy the trait
         MetaPluginType::Text
     }
     
+    /// Returns a reference to the outputs mapping.
+    ///
+    /// # Returns
+    ///
+    /// A reference to the `HashMap` of outputs.
     fn outputs(&self) -> &std::collections::HashMap<String, serde_yaml::Value> {
         &self.outputs
     }
     
+    /// Returns a mutable reference to the outputs mapping.
+    ///
+    /// # Returns
+    ///
+    /// A mutable reference to the `HashMap` of outputs.
     fn outputs_mut(&mut self) -> &mut std::collections::HashMap<String, serde_yaml::Value> {
         &mut self.outputs
     }
     
+    /// Returns a reference to the options mapping.
+    ///
+    /// # Returns
+    ///
+    /// A reference to the `HashMap` of options.
     fn options(&self) -> &std::collections::HashMap<String, serde_yaml::Value> {
         &self.options
     }
     
+    /// Returns a mutable reference to the options mapping.
+    ///
+    /// # Returns
+    ///
+    /// A mutable reference to the `HashMap` of options.
     fn options_mut(&mut self) -> &mut std::collections::HashMap<String, serde_yaml::Value> {
         &mut self.options
     }
@@ -142,8 +205,17 @@ pub enum MetaPluginType {
     Env,
 }
 
-/// Central function to handle metadata output with name mapping
-/// outputs: HashMap where key is internal name, value is either custom name or "false" to disable
+/// Central function to handle metadata output with name mapping.
+///
+/// # Arguments
+///
+/// * `internal_name` - The internal name of the metadata.
+/// * `value` - The value to process.
+/// * `outputs` - The outputs mapping.
+///
+/// # Returns
+///
+/// An optional `MetaData` if the output is enabled, `None` if disabled.
 pub fn process_metadata_outputs(internal_name: &str, value: serde_yaml::Value, outputs: &std::collections::HashMap<String, serde_yaml::Value>) -> Option<MetaData> {
     // Check if this output is disabled
     if let Some(mapping) = outputs.get(internal_name) {
@@ -198,25 +270,56 @@ pub fn process_metadata_outputs(internal_name: &str, value: serde_yaml::Value, o
 }
 
 pub trait MetaPlugin where Self: 'static {
+    /// Returns the type of this meta plugin.
+    ///
+    /// # Returns
+    ///
+    /// The `MetaPluginType` enum variant for this plugin.
     fn meta_type(&self) -> MetaPluginType;
     
+    /// Checks if the plugin is supported on the current system.
+    ///
+    /// # Returns
+    ///
+    /// `true` if supported, `false` otherwise.
     fn is_supported(&self) -> bool {
         true
     }
     
+    /// Checks if the plugin is internal (built-in).
+    ///
+    /// # Returns
+    ///
+    /// `true` if internal, `false` otherwise.
     fn is_internal(&self) -> bool {
         true
     }
     
-    // Check if the plugin is already finalized
+    /// Checks if the plugin is already finalized.
+    ///
+    /// # Returns
+    ///
+    /// `true` if finalized, `false` otherwise.
     fn is_finalized(&self) -> bool {
         false
     }
     
-    // Set the finalized state (only for plugins that can track this)
+    /// Sets the finalized state (only for plugins that can track this).
+    ///
+    /// # Arguments
+    ///
+    /// * `_finalized` - The new finalized state (unused in default).
     fn set_finalized(&mut self, _finalized: bool) {}
     
-    // Update the meta plugin with new data
+    /// Updates the meta plugin with new data.
+    ///
+    /// # Arguments
+    ///
+    /// * `_data` - The data chunk to process (unused in default).
+    ///
+    /// # Returns
+    ///
+    /// A `MetaPluginResponse` with empty metadata and `is_finalized` set to `false`.
     fn update(&mut self, _data: &[u8]) -> MetaPluginResponse {
         // Default implementation does nothing
         MetaPluginResponse {
@@ -225,6 +328,11 @@ pub trait MetaPlugin where Self: 'static {
         }
     }
 
+    /// Finalizes the plugin.
+    ///
+    /// # Returns
+    ///
+    /// A `MetaPluginResponse` with empty metadata and `is_finalized` set to `true`.
     fn finalize(&mut self) -> MetaPluginResponse {
         // Default implementation does nothing
         MetaPluginResponse {
@@ -233,12 +341,20 @@ pub trait MetaPlugin where Self: 'static {
         }
     }
     
-    // Get program information for display in status
+    /// Gets program information for display in status.
+    ///
+    /// # Returns
+    ///
+    /// An optional tuple of program name and arguments, or `None`.
     fn program_info(&self) -> Option<(&str, Vec<&str>)> {
         None
     }
     
-    // Initialize the plugin
+    /// Initializes the plugin.
+    ///
+    /// # Returns
+    ///
+    /// A `MetaPluginResponse` with empty metadata and `is_finalized` set to `false`.
     fn initialize(&mut self) -> MetaPluginResponse {
         // Default implementation does nothing
         MetaPluginResponse {
@@ -247,7 +363,11 @@ pub trait MetaPlugin where Self: 'static {
         }
     }
     
-    // Access to outputs mapping with default implementation
+    /// Returns a reference to the outputs mapping.
+    ///
+    /// # Returns
+    ///
+    /// An empty `HashMap` (default implementation).
     fn outputs(&self) -> &std::collections::HashMap<String, serde_yaml::Value> {
         use once_cell::sync::Lazy;
         static EMPTY: Lazy<std::collections::HashMap<String, serde_yaml::Value>> = 
@@ -255,11 +375,20 @@ pub trait MetaPlugin where Self: 'static {
         &EMPTY
     }
     
+    /// Returns a mutable reference to the outputs mapping.
+    ///
+    /// # Panics
+    ///
+    /// Panics with "outputs_mut() not implemented for this plugin".
     fn outputs_mut(&mut self) -> &mut std::collections::HashMap<String, serde_yaml::Value> {
         panic!("outputs_mut() not implemented for this plugin")
     }
     
-    // Access to options mapping with default implementation
+    /// Returns a reference to the options mapping.
+    ///
+    /// # Returns
+    ///
+    /// An empty `HashMap` (default implementation).
     fn options(&self) -> &std::collections::HashMap<String, serde_yaml::Value> {
         use once_cell::sync::Lazy;
         static EMPTY: Lazy<std::collections::HashMap<String, serde_yaml::Value>> = 
@@ -267,11 +396,20 @@ pub trait MetaPlugin where Self: 'static {
         &EMPTY
     }
     
+    /// Returns a mutable reference to the options mapping.
+    ///
+    /// # Panics
+    ///
+    /// Panics with "options_mut() not implemented for this plugin".
     fn options_mut(&mut self) -> &mut std::collections::HashMap<String, serde_yaml::Value> {
         panic!("options_mut() not implemented for this plugin")
     }
     
-    // Get the default output names this plugin can produce
+    /// Gets the default output names this plugin can produce.
+    ///
+    /// # Returns
+    ///
+    /// A vector containing the meta type as a string (default).
     fn default_outputs(&self) -> Vec<String> {
         // Default implementation returns the meta type as a string
         vec![self.meta_type().to_string()]
@@ -279,17 +417,26 @@ pub trait MetaPlugin where Self: 'static {
     
     
     
-    // Method to downcast to concrete type (for checking finalization state)
+    /// Method to downcast to concrete type (for checking finalization state).
+    ///
+    /// # Returns
+    ///
+    /// A mutable reference to `self` as `dyn Any`.
     fn as_any_mut(&mut self) -> &mut dyn std::any::Any where Self: Sized {
         self
     }
 }
 
-/// Global registry for meta plugins
+/// Global registry for meta plugins.
 static META_PLUGIN_REGISTRY: Lazy<Mutex<HashMap<MetaPluginType, fn(Option<HashMap<String, serde_yaml::Value>>, Option<HashMap<String, serde_yaml::Value>>) -> Box<dyn MetaPlugin>>>> = 
     Lazy::new(|| Mutex::new(HashMap::new()));
 
-/// Register a meta plugin with the global registry
+/// Register a meta plugin with the global registry.
+///
+/// # Arguments
+///
+/// * `meta_plugin_type` - The type of the meta plugin to register.
+/// * `constructor` - The constructor function for creating plugin instances.
 pub fn register_meta_plugin(
     meta_plugin_type: MetaPluginType, 
     constructor: fn(Option<HashMap<String, serde_yaml::Value>>, Option<HashMap<String, serde_yaml::Value>>) -> Box<dyn MetaPlugin>