docs: Add Rustdoc to meta_plugin, filter_plugin, common, lib, and filter_service

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

PLAN.md

@@ -44,28 +44,28 @@ Private helpers (e.g., internal `fn` without `pub`) are not flagged, as they don
    - `get_tags_for_items()` and `get_meta_for_items()` functions: Partial.
    - Overall: Many CRUD functions lack full docs; the module-level doc is good but individual items are inconsistent.
 
-3. **src/meta_plugin/read_rate.rs**
+3. **src/meta_plugin/read_rate.rs** [DONE]
    - `ReadRateMetaPlugin` struct: Missing doc comment.
    - `new()` function: Partial (missing full param docs).
    - Impl `MetaPlugin` methods (`is_finalized`, `set_finalized`, `finalize`, `update`, `meta_type`, `outputs`, etc.): No docs.
    - Overall: Lacks docs for the public trait impl.
 
-4. **src/filter_plugin/head.rs**
+4. **src/filter_plugin/head.rs** [DONE]
    - `HeadBytesFilter` and `HeadLinesFilter` structs: No docs.
    - `new()` functions: Partial.
    - Impl `FilterPlugin` methods (`filter`, `clone_box`, `options`): No docs.
    - Overall: No rustdoc at all for public impl.
 
-5. **src/common/binary_detection.rs**
+5. **src/common/binary_detection.rs** [DONE]
    - `check_binary_content_allowed()` function: Partial (missing examples).
    - `is_content_binary()` function: Partial.
    - Overall: Functions lack full error handling docs.
 
-6. **src/lib.rs**
+6. **src/lib.rs** [DONE]
    - Module re-exports and `init_plugins()` function: No docs.
    - Overall: Library-level docs are minimal.
 
-7. **src/services/filter_service.rs**
+7. **src/services/filter_service.rs** [DONE]
    - `FilterService` struct: Partial doc.
    - `new()`, `create_filter_chain()`, `filter_data()`, `process_with_filter()` methods: Partial or missing.
    - `register_filter_plugin()` and `get_available_filter_plugins()` functions: Partial.

src/services/filter_service.rs

@@ -110,19 +110,24 @@ impl FilterService {
         }
     }
 
-    /// Processes data with an optional filter string in a single call.
+    /// Convenience method to apply filters to in-memory data and return the result.
     ///
-    /// This is a convenience method that creates a filter chain, applies it to the data,
+    /// Parses the filter string, applies the chain to the data via Cursor I/O,
-    /// and returns the filtered result as a byte vector. Useful for simple one-off filtering.
+    /// and collects output into a Vec<u8>. Ideal for non-streaming use cases.
     ///
     /// # Arguments
     ///
-    /// * `data` - Input byte slice to process.
+    /// * `data` - Input bytes to filter.
-    /// * `filter_str` - Optional filter string to apply.
+    /// * `filter_str` - Optional filter string specification.
     ///
     /// # Returns
     ///
-    /// * `Result<Vec<u8>, io::Error>` - Filtered data or error if filtering fails.
+    /// * `Ok(Vec<u8>)` - Filtered output bytes.
+    /// * `Err(io::Error)` - If chain creation or filtering fails.
+    ///
+    /// # Errors
+    ///
+    /// Propagates parsing or I/O errors.
     ///
     /// # Examples
     ///
@@ -145,64 +150,57 @@ impl FilterService {
     }
 }
 
-/// Global registry for filter plugins.
+/// Global thread-safe registry for filter plugins.
 ///
-/// This static variable holds a thread-safe map of filter plugin names to their
+/// Lazily initialized Mutex<HashMap> mapping plugin names (e.g., "head_bytes") to their constructors.
-/// constructors. Plugins register themselves at initialization time using
+/// Plugins self-register via ctors at module load time. Used by the parser to instantiate filters dynamically.
-/// `register_filter_plugin`. The registry is lazily initialized on first access.
-///
-/// # Usage
-///
-/// Plugins use this registry for dynamic loading:
-///
-/// ```rust
-/// static FILTER_PLUGIN_REGISTRY: Lazy<Mutex<HashMap<String, fn() -> Box<dyn FilterPlugin>>>> = 
-///     Lazy::new(|| Mutex::new(HashMap::new()));
-/// ```
-static FILTER_PLUGIN_REGISTRY: Lazy<Mutex<HashMap<String, fn() -> Box<dyn crate::filter_plugin::FilterPlugin>>>> = 
-    Lazy::new(|| Mutex::new(HashMap::new()));
-
-/// Register a filter plugin with the global registry.
-///
-/// Adds a filter plugin to the registry so it can be dynamically loaded by name.
-/// This function is typically called at module initialization time using `#[ctor::ctor]`.
-///
-/// # Arguments
-///
-/// * `name` - The name of the filter plugin (e.g., "head_lines").
-/// * `constructor` - A function that returns a new `Box<dyn FilterPlugin>` instance.
 ///
 /// # Panics
 ///
-/// Panics if the registry lock cannot be acquired (unlikely in normal use).
+/// Lock acquisition failures (rare) cause panics in accessors.
+static FILTER_PLUGIN_REGISTRY: Lazy<Mutex<HashMap<String, fn() -> Box<dyn crate::filter_plugin::FilterPlugin>>>> = 
+    Lazy::new(|| Mutex::new(HashMap::new()));
+
+/// Registers a filter plugin in the global registry.
+///
+/// Called by plugin modules at initialization to enable dynamic loading by name.
+/// Supports plugin discovery and instantiation during filter chain parsing.
+///
+/// # Arguments
+///
+/// * `name` - Unique string identifier for the plugin (e.g., "head_lines").
+/// * `constructor` - Zero-arg function returning a new boxed `FilterPlugin` instance.
+///
+/// # Panics
+///
+/// Panics if Mutex lock fails (unlikely).
 ///
 /// # Examples
 ///
 /// ```rust
-/// register_filter_plugin("my_filter", || Box::new(MyFilter::new()));
+/// register_filter_plugin("custom_filter", || Box::new(CustomFilter::default()));
 /// ```
 pub fn register_filter_plugin(name: &str, constructor: fn() -> Box<dyn crate::filter_plugin::FilterPlugin>) {
     FILTER_PLUGIN_REGISTRY.lock().unwrap().insert(name.to_string(), constructor);
 }
 
-/// Get a map of available filter plugins.
+/// Retrieves a snapshot of all registered filter plugins.
 ///
-/// Returns a copy of the current registry contents, mapping plugin names to their constructors.
+/// Clones the registry for safe iteration. Useful for status reporting, validation, or UI display of available filters.
-/// This is useful for status reporting or plugin discovery.
 ///
 /// # Returns
 ///
-/// `HashMap<String, fn() -> Box<dyn FilterPlugin>>` - A clone of the registry map.
+/// HashMap clone with plugin names as keys and constructors as values.
 ///
 /// # Panics
 ///
-/// Panics if the registry lock cannot be acquired.
+/// Panics if Mutex lock fails.
 ///
 /// # Examples
 ///
 /// ```rust
-/// let available = get_available_filter_plugins();
+/// let plugins = get_available_filter_plugins();
-/// assert!(available.contains_key("head_lines"));
+/// assert!(plugins.contains_key("head_bytes"));
 /// ```
 pub fn get_available_filter_plugins() -> HashMap<String, fn() -> Box<dyn crate::filter_plugin::FilterPlugin>> {
     FILTER_PLUGIN_REGISTRY.lock().unwrap().clone()