docs: Add comprehensive Rustdoc to src/meta_plugin/read_rate.rs

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

src/meta_plugin/read_rate.rs

@@ -3,6 +3,19 @@ use std::time::Instant;
 use crate::meta_plugin::{MetaPlugin, MetaPluginType};
 
 #[derive(Debug, Clone, Default)]
+/// Meta plugin that calculates the read rate (KB/s) of input data.
+///
+/// Tracks bytes read and elapsed time, then computes the rate in finalize(). 
+/// Outputs the rate via configured mappings. Supports options for customization
+/// (though defaults are used here).
+///
+/// # Fields
+///
+/// * `start_time` - Start time of reading, if begun.
+/// * `bytes_read` - Total bytes accumulated.
+/// * `is_finalized` - Whether processing is complete.
+/// * `outputs` - Mapping of output names to values.
+/// * `options` - Configuration options.
 pub struct ReadRateMetaPlugin {
     start_time: Option<Instant>,
     bytes_read: u64,
@@ -14,14 +27,24 @@ pub struct ReadRateMetaPlugin {
 impl ReadRateMetaPlugin {
     /// Creates a new `ReadRateMetaPlugin` instance.
     ///
+    /// Initializes with default options and outputs, merging provided ones.
+    /// Starts tracking from zero bytes and no start time.
+    ///
     /// # Arguments
     ///
-    /// * `_options` - Optional configuration options for the plugin (unused in this implementation).
-    /// * `outputs` - Optional output mappings for metadata.
+    /// * `_options` - Optional configuration options (merged with defaults; unused specifics here).
+    /// * `outputs` - Optional output mappings (merged with default "read_rate").
     ///
     /// # Returns
     ///
-    /// A new instance of `ReadRateMetaPlugin`.
+    /// A new, un-finalized `ReadRateMetaPlugin` instance.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let plugin = ReadRateMetaPlugin::new(None, None);
+    /// assert!(!plugin.is_finalized());
+    /// ```
     pub fn new(
         _options: Option<std::collections::HashMap<String, serde_yaml::Value>>,
         outputs: Option<std::collections::HashMap<String, serde_yaml::Value>>,
@@ -62,25 +85,34 @@ impl MetaPlugin for ReadRateMetaPlugin {
     ///
     /// # Returns
     ///
-    /// `true` if finalized, `false` otherwise.
+    /// `true` if finalized (processing complete), `false` otherwise.
     fn is_finalized(&self) -> bool {
         self.is_finalized
     }
     
     /// Sets the finalized state of the plugin.
     ///
+    /// Marks the plugin as complete or resets it.
+    ///
     /// # Arguments
     ///
-    /// * `finalized` - The new finalized state.
+    /// * `finalized` - Whether processing is now complete.
     fn set_finalized(&mut self, finalized: bool) {
         self.is_finalized = finalized;
     }
     
     /// Finalizes the plugin, calculating the read rate.
     ///
+    /// Computes KB/s from bytes read and elapsed time. Outputs via mappings.
+    /// Idempotent: skips if already finalized.
+    ///
     /// # Returns
     ///
-    /// A `MetaPluginResponse` with read rate metadata and finalized state set to `true`.
+    /// A `MetaPluginResponse` with rate metadata (if computable) and finalized=true.
+    ///
+    /// # Errors
+    ///
+    /// None; returns empty metadata if no start time or zero duration.
     fn finalize(&mut self) -> crate::meta_plugin::MetaPluginResponse {
         // If already finalized, don't process again
         if self.is_finalized {
@@ -121,13 +153,16 @@ impl MetaPlugin for ReadRateMetaPlugin {
 
     /// Updates the plugin with new data, accumulating bytes read.
     ///
+    /// Starts timer on first update if not set. Accumulates byte count.
+    /// Idempotent post-finalize: ignores data.
+    ///
     /// # Arguments
     ///
-    /// * `data` - The data chunk to process.
+    /// * `data` - Byte slice to process (length added to total).
     ///
     /// # Returns
     ///
-    /// A `MetaPluginResponse` with empty metadata and finalized state set to `false`.
+    /// `MetaPluginResponse` with no metadata and finalized=false (unless already done).
     fn update(&mut self, data: &[u8]) -> crate::meta_plugin::MetaPluginResponse {
         // If already finalized, don't process more data
         if self.is_finalized {
@@ -160,16 +195,18 @@ impl MetaPlugin for ReadRateMetaPlugin {
     ///
     /// # Returns
     ///
-    /// A reference to the `HashMap` of outputs.
+    /// Immutable reference to the outputs HashMap.
     fn outputs(&self) -> &std::collections::HashMap<String, serde_yaml::Value> {
         &self.outputs
     }
     
     /// Returns a mutable reference to the outputs mapping.
     ///
+    /// Allows modification of output configurations.
+    ///
     /// # Returns
     ///
-    /// A mutable reference to the `HashMap` of outputs.
+    /// Mutable reference to the outputs HashMap.
     fn outputs_mut(&mut self) -> &mut std::collections::HashMap<String, serde_yaml::Value> {
         &mut self.outputs
     }
@@ -180,20 +217,23 @@ impl MetaPlugin for ReadRateMetaPlugin {
     ///
     /// # Returns
     ///
-    /// A reference to the `HashMap` of options.
+    /// Immutable reference to the options HashMap.
     fn options(&self) -> &std::collections::HashMap<String, serde_yaml::Value> {
         &self.options
     }
     
     /// Returns a mutable reference to the options mapping.
     ///
+    /// Allows modification of plugin options.
+    ///
     /// # Returns
     ///
-    /// A mutable reference to the `HashMap` of options.
+    /// Mutable reference to the options HashMap.
     fn options_mut(&mut self) -> &mut std::collections::HashMap<String, serde_yaml::Value> {
         &mut self.options
     }
 }
+}
 use crate::meta_plugin::register_meta_plugin;
 
 // Register the plugin at module initialization time