From 3ddecc9ed5dbb36f7ce8cdd732f72d03ae9aac00 Mon Sep 17 00:00:00 2001
From: Andrew Phillips <andrew.phillips2@canada.ca>
Date: Wed, 10 Sep 2025 15:12:49 -0300
Subject: [PATCH] docs: Add comprehensive Rustdoc for ExecFilter and its
 methods

Co-authored-by: aider (openai/andrew/openrouter/sonoma-sky-alpha) <aider@aider.chat>
---
 src/filter_plugin/exec.rs | 44 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 43 insertions(+), 1 deletion(-)

diff --git a/src/filter_plugin/exec.rs b/src/filter_plugin/exec.rs
index 43e79e4..ceed2be 100644
--- a/src/filter_plugin/exec.rs
+++ b/src/filter_plugin/exec.rs
@@ -5,6 +5,10 @@ use which::which;
 use log::*;
 
 /// A filter that executes an external program and pipes input through it.
+///
+/// This filter spawns an external command, pipes the input stream to its stdin,
+/// and writes the stdout to the output stream. Supports async-like behavior via
+/// threads for concurrent I/O. Requires the program to be available on PATH.
 #[derive(Debug, Clone)]
 pub struct ExecFilter {
     program: String,
@@ -19,11 +23,26 @@ pub struct ExecFilter {
 impl ExecFilter {
     /// Creates a new `ExecFilter` for the specified program and arguments.
     ///
+    /// Checks if the program is available using `which` and stores the resolved path.
+    ///
     /// # Arguments
     ///
     /// * `program` - The name or path of the program to execute.
     /// * `args` - A slice of string slices representing the arguments to pass to the program.
-    /// * `split_whitespace` - Whether to split arguments on whitespace when parsing.
+    /// * `split_whitespace` - Whether to split arguments on whitespace when parsing (unused in this context).
+    ///
+    /// # Returns
+    ///
+    /// A new `ExecFilter` instance.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use keep::filter_plugin::exec::ExecFilter;
+    ///
+    /// let filter = ExecFilter::new("grep", vec!["-i", "error"], false);
+    /// assert!(filter.supported);
+    /// ```
     pub fn new(
         program: &str,
         args: Vec<&str>,
@@ -47,6 +66,9 @@ impl ExecFilter {
 impl FilterPlugin for ExecFilter {
     /// Filters the input by piping it through the external program and writing the output.
     ///
+    /// Spawns the process with piped I/O, uses threads for concurrent input/output
+    /// copying, and waits for completion. Errors if the program isn't found or fails.
+    ///
     /// # Arguments
     ///
     /// * `reader` - A boxed mutable reference to the input reader providing the data stream to pipe to the program.
@@ -55,6 +77,22 @@ impl FilterPlugin for ExecFilter {
     /// # Returns
     ///
     /// Returns `Ok(())` on success, or an `io::Error` if process spawning, piping, or execution fails.
+    ///
+    /// # Errors
+    ///
+    /// * NotFound - Program not available.
+    /// * Other - Spawn, I/O, or wait failures.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use keep::filter_plugin::exec::ExecFilter;
+    /// use std::io::{Read, Write};
+    ///
+    /// let mut filter = ExecFilter::new("cat", vec![], false);
+    /// // In filter context:
+    /// filter.filter(Box::new(&mut input), Box::new(&mut output)).unwrap();
+    /// ```
     fn filter(&mut self, mut reader: Box<&mut dyn Read>, mut writer: Box<&mut dyn Write>) -> Result<()> {
         if !self.supported {
             return Err(std::io::Error::new(
@@ -166,6 +204,8 @@ impl FilterPlugin for ExecFilter {
 
     /// Clones this filter into a new boxed instance.
     ///
+    /// Creates a new instance without active process handles.
+    ///
     /// # Returns
     ///
     /// A new `Box<dyn FilterPlugin>` representing a clone of this filter.
@@ -183,6 +223,8 @@ impl FilterPlugin for ExecFilter {
 
     /// Returns the configuration options for this filter.
     ///
+    /// Defines "command" as required and "split_whitespace" as optional.
+    ///
     /// # Returns
     ///
     /// A vector of `FilterOption` describing the filter's configurable parameters.