From b8263ee29e996e9976be4714cbc717f95a0bbff3 Mon Sep 17 00:00:00 2001 From: Andrew Phillips Date: Wed, 10 Sep 2025 15:42:43 -0300 Subject: [PATCH] docs: Add comprehensive Rustdoc to src/meta_plugin/read_rate.rs Co-authored-by: aider (openai/andrew/openrouter/sonoma-sky-alpha) --- src/meta_plugin/read_rate.rs | 64 +++++++++++++++++++++++++++++------- 1 file changed, 52 insertions(+), 12 deletions(-) diff --git a/src/meta_plugin/read_rate.rs b/src/meta_plugin/read_rate.rs index dceeefb..d8e0813 100644 --- a/src/meta_plugin/read_rate.rs +++ b/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, 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>, outputs: Option>, @@ -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 { &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 { &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 { &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 { &mut self.options } } +} use crate::meta_plugin::register_meta_plugin; // Register the plugin at module initialization time