docs: Add comprehensive Rustdoc comments to public APIs

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

src/filter_plugin/mod.rs

@@ -2,6 +2,20 @@ use std::io::{Result, Read, Write};
 use std::str::FromStr;
 use strum::EnumString;
 
+/// Filter plugin module for processing input streams.
+///
+/// This module defines the `FilterPlugin` trait and `FilterChain` for chaining filters,
+/// along with parsing utilities for filter strings. Filters can process data like head/tail,
+/// grep, etc.
+///
+/// # Usage
+///
+/// Parse a filter string and apply to a reader:
+///
+/// ```
+/// let chain = parse_filter_string("head_lines(10)|grep(pattern=error)")?;
+/// chain.filter(&mut reader, &mut writer)?;
+/// ```
 pub mod head;
 pub mod tail;
 pub mod skip;
@@ -18,6 +32,14 @@ pub use grep::GrepFilter;
 pub use strip_ansi::StripAnsiFilter;
 
 /// Represents an option for a filter plugin.
+///
+/// Defines a configurable parameter for filters, with name, default, and required flag.
+///
+/// # Fields
+///
+/// * `name` - Option name.
+/// * `default` - Optional default value.
+/// * `required` - If true, must be provided.
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize, utoipa::ToSchema)]
 pub struct FilterOption {
     pub name: String,
@@ -27,6 +49,25 @@ pub struct FilterOption {
 }
 
 /// Trait for filter plugins that process input streams.
+///
+/// Implement this trait to create a filter that reads from an input stream and writes filtered output.
+///
+/// # Required Methods
+///
+/// * `filter` - Process the stream.
+/// * `clone_box` - For cloning dynamic instances.
+/// * `options` - Describe configurable options.
+///
+/// # Examples
+///
+/// ```
+/// impl FilterPlugin for MyFilter {
+///     fn filter(&mut self, reader: Box<&mut dyn Read>, writer: Box<&mut dyn Write>) -> Result<()> {
+///         // Implementation
+///     }
+///     // ...
+/// }
+/// ```
 pub trait FilterPlugin: Send {
     /// Processes the input stream and writes the filtered output.
     ///
@@ -54,6 +95,14 @@ pub trait FilterPlugin: Send {
 }
 
 /// Enum representing the different types of filters.
+///
+/// Used for parsing and instantiating specific filter plugins.
+///
+/// # Variants
+///
+/// * `HeadBytes` - Head by bytes.
+/// * `HeadLines` - Head by lines.
+/// * ... etc.
 #[derive(Debug, EnumString, strum::VariantNames, strum::Display)]
 #[strum(serialize_all = "snake_case")]
 pub enum FilterType {
@@ -68,6 +117,12 @@ pub enum FilterType {
 }
 
 /// A chain of filter plugins applied sequentially.
+///
+/// Chains multiple filters, applying them in order to the input stream.
+///
+/// # Fields
+///
+/// * `plugins` - Vector of boxed filter plugins.
 pub struct FilterChain {
     plugins: Vec<Box<dyn FilterPlugin>>,
 }