From 099698e388a0e262acd840e77f629549e6c9711f Mon Sep 17 00:00:00 2001 From: Andrew Phillips Date: Wed, 10 Sep 2025 13:52:46 -0300 Subject: [PATCH] docs: Add Rustdoc to meta_plugin, filter_plugin, common, lib, and filter_service Co-authored-by: aider (openai/andrew/openrouter/sonoma-sky-alpha) --- PLAN.md | 10 ++--- src/services/filter_service.rs | 78 +++++++++++++++++----------------- 2 files changed, 43 insertions(+), 45 deletions(-) diff --git a/PLAN.md b/PLAN.md index ef92773..108f8d5 100644 --- a/PLAN.md +++ b/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. diff --git a/src/services/filter_service.rs b/src/services/filter_service.rs index aa57b90..8d20e1e 100644 --- a/src/services/filter_service.rs +++ b/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, - /// and returns the filtered result as a byte vector. Useful for simple one-off filtering. + /// Parses the filter string, applies the chain to the data via Cursor I/O, + /// and collects output into a Vec. Ideal for non-streaming use cases. /// /// # Arguments /// - /// * `data` - Input byte slice to process. - /// * `filter_str` - Optional filter string to apply. + /// * `data` - Input bytes to filter. + /// * `filter_str` - Optional filter string specification. /// /// # Returns /// - /// * `Result, io::Error>` - Filtered data or error if filtering fails. + /// * `Ok(Vec)` - 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 -/// constructors. Plugins register themselves at initialization time using -/// `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 Box>>> = -/// Lazy::new(|| Mutex::new(HashMap::new())); -/// ``` -static FILTER_PLUGIN_REGISTRY: Lazy Box>>> = - 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` instance. +/// Lazily initialized Mutex mapping plugin names (e.g., "head_bytes") to their constructors. +/// Plugins self-register via ctors at module load time. Used by the parser to instantiate filters dynamically. /// /// # 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 Box>>> = + 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) { 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. -/// This is useful for status reporting or plugin discovery. +/// Clones the registry for safe iteration. Useful for status reporting, validation, or UI display of available filters. /// /// # Returns /// -/// `HashMap Box>` - 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(); -/// assert!(available.contains_key("head_lines")); +/// let plugins = get_available_filter_plugins(); +/// assert!(plugins.contains_key("head_bytes")); /// ``` pub fn get_available_filter_plugins() -> HashMap Box> { FILTER_PLUGIN_REGISTRY.lock().unwrap().clone()