docs: Document arguments and returns for utility and filter functions

Co-authored-by: aider (openai/andrew/openrouter/deepseek/deepseek-chat-v3.1) <aider@aider.chat>

src/filter_plugin/head.rs

@@ -13,11 +13,11 @@ impl HeadBytesFilter {
     ///
     /// # Arguments
     ///
-    /// * `count` - The maximum number of bytes to read from the input.
+    /// * `count` - The maximum number of bytes to read from the input
     ///
     /// # Returns
     ///
-    /// A new instance of `HeadBytesFilter`.
+    /// * `Self` - A new instance of `HeadBytesFilter`
     pub fn new(count: usize) -> Self {
         Self {
             remaining: count,
@@ -30,12 +30,14 @@ impl FilterPlugin for HeadBytesFilter {
     ///
     /// # Arguments
     ///
-    /// * `reader` - A boxed mutable reference to the input reader providing the data stream.
-    /// * `writer` - A boxed mutable reference to the output writer where filtered data is sent.
+    /// * `reader` - A boxed mutable reference to the input reader providing the data stream
+    /// * `writer` - A boxed mutable reference to the output writer where filtered data is sent
     ///
     /// # Returns
     ///
-    /// Returns `Ok(())` on success, or an `io::Error` if reading or writing fails.
+    /// * `Result<()>` - 
+    ///     * `Ok(())` on success
+    ///     * `Err(io::Error)` if reading or writing fails
     fn filter(&mut self, mut reader: Box<&mut dyn Read>, mut writer: Box<&mut dyn Write>) -> Result<()> {
         if self.remaining == 0 {
             return Ok(());
@@ -58,7 +60,7 @@ impl FilterPlugin for HeadBytesFilter {
     ///
     /// # Returns
     ///
-    /// A new `Box<dyn FilterPlugin>` representing a clone of this filter.
+    /// * `Box<dyn FilterPlugin>` - A new boxed clone of this filter
     fn clone_box(&self) -> Box<dyn FilterPlugin> {
         Box::new(Self {
             remaining: self.remaining,
@@ -69,7 +71,7 @@ impl FilterPlugin for HeadBytesFilter {
     ///
     /// # Returns
     ///
-    /// A vector of `FilterOption` describing the filter's configurable parameters.
+    /// * `Vec<FilterOption>` - A vector describing the filter's configurable parameters
     fn options(&self) -> Vec<FilterOption> {
         vec![
             FilterOption {
@@ -91,11 +93,11 @@ impl HeadLinesFilter {
     ///
     /// # Arguments
     ///
-    /// * `count` - The maximum number of lines to read from the input.
+    /// * `count` - The maximum number of lines to read from the input
     ///
     /// # Returns
     ///
-    /// A new instance of `HeadLinesFilter`.
+    /// * `Self` - A new instance of `HeadLinesFilter`
     pub fn new(count: usize) -> Self {
         Self {
             remaining: count,
@@ -108,12 +110,14 @@ impl FilterPlugin for HeadLinesFilter {
     ///
     /// # Arguments
     ///
-    /// * `reader` - A boxed mutable reference to the input reader providing the data stream.
-    /// * `writer` - A boxed mutable reference to the output writer where filtered data is sent.
+    /// * `reader` - A boxed mutable reference to the input reader providing the data stream
+    /// * `writer` - A boxed mutable reference to the output writer where filtered data is sent
     ///
     /// # Returns
     ///
-    /// Returns `Ok(())` on success, or an `io::Error` if reading or writing fails.
+    /// * `Result<()>` - 
+    ///     * `Ok(())` on success
+    ///     * `Err(io::Error)` if reading or writing fails
     fn filter(&mut self, mut reader: Box<&mut dyn Read>, mut writer: Box<&mut dyn Write>) -> Result<()> {
         if self.remaining == 0 {
             return Ok(());
@@ -135,7 +139,7 @@ impl FilterPlugin for HeadLinesFilter {
     ///
     /// # Returns
     ///
-    /// A new `Box<dyn FilterPlugin>` representing a clone of this filter.
+    /// * `Box<dyn FilterPlugin>` - A new boxed clone of this filter
     fn clone_box(&self) -> Box<dyn FilterPlugin> {
         Box::new(Self {
             remaining: self.remaining,
@@ -146,7 +150,7 @@ impl FilterPlugin for HeadLinesFilter {
     ///
     /// # Returns
     ///
-    /// A vector of `FilterOption` describing the filter's configurable parameters.
+    /// * `Vec<FilterOption>` - A vector describing the filter's configurable parameters
     fn options(&self) -> Vec<FilterOption> {
         vec![
             FilterOption {

src/filter_plugin/utils.rs

@@ -4,11 +4,14 @@ use std::io::Result;
 ///
 /// # Arguments
 ///
-/// * `filter_str` - The string describing the filter chain, such as "head_lines(10)|grep(pattern=error)".
+/// * `filter_str` - The string describing the filter chain, such as "head_lines(10)|grep(pattern=error)"
 ///
 /// # Returns
 ///
-/// A `Result` containing an optional `FilterChain` if parsing succeeds, wrapped in `Some`, or an error if invalid.
+/// * `Result<Option<super::FilterChain>>` - A result containing:
+///     * `Ok(Some(FilterChain))` if parsing succeeds
+///     * `Ok(None)` if the filter string is empty
+///     * `Err(io::Error)` if the string is invalid
 pub fn create_filter_chain(filter_str: &str) -> Result<Option<super::FilterChain>> {
     super::parse_filter_string(filter_str).map(Some)
 }
@@ -17,11 +20,13 @@ pub fn create_filter_chain(filter_str: &str) -> Result<Option<super::FilterChain
 ///
 /// # Arguments
 ///
-/// * `s` - The string to parse into a number.
+/// * `s` - The string to parse into a number
 ///
 /// # Returns
 ///
-/// A `Result` containing the parsed value of type T on success, or an `io::Error` if the string is not a valid number.
+/// * `Result<T>` - A result containing:
+///     * `Ok(T)` - The parsed number on success
+///     * `Err(io::Error)` - If the string is not a valid number
 pub fn parse_number<T: std::str::FromStr>(s: &str) -> Result<T> {
     s.parse::<T>()
         .map_err(|_| std::io::Error::new(std::io::ErrorKind::InvalidInput, "Invalid number"))