From cb716c161cd645da3f0f93c6e0dbd52911245e96 Mon Sep 17 00:00:00 2001 From: Andrew Phillips Date: Wed, 10 Sep 2025 10:59:29 -0300 Subject: [PATCH] docs: Document arguments and returns for utility and filter functions Co-authored-by: aider (openai/andrew/openrouter/deepseek/deepseek-chat-v3.1) --- src/common/binary_detection.rs | 26 ++++++++++++++++++++++++++ src/filter_plugin/head.rs | 32 ++++++++++++++++++-------------- src/filter_plugin/utils.rs | 13 +++++++++---- 3 files changed, 53 insertions(+), 18 deletions(-) diff --git a/src/common/binary_detection.rs b/src/common/binary_detection.rs index 7c61dd7..d58db52 100644 --- a/src/common/binary_detection.rs +++ b/src/common/binary_detection.rs @@ -4,6 +4,19 @@ use axum::http::StatusCode; use std::collections::HashMap; /// Check if content is binary when allow_binary is false +/// +/// # Arguments +/// +/// * `item_service` - Reference to the async item service +/// * `item_id` - The ID of the item to check +/// * `metadata` - Metadata associated with the item +/// * `allow_binary` - Whether binary content is allowed +/// +/// # Returns +/// +/// * `Result<(), StatusCode>` - +/// * `Ok(())` if binary content is allowed or content is not binary +/// * `Err(StatusCode::BAD_REQUEST)` if binary content is not allowed and content is binary pub async fn check_binary_content_allowed( item_service: &AsyncItemService, item_id: i64, @@ -20,6 +33,19 @@ pub async fn check_binary_content_allowed( } /// Helper function to determine if content is binary +/// +/// # Arguments +/// +/// * `item_service` - Reference to the async item service +/// * `item_id` - The ID of the item to check +/// * `metadata` - Metadata associated with the item +/// +/// # Returns +/// +/// * `Result` - +/// * `Ok(true)` if content is binary +/// * `Ok(false)` if content is text +/// * `Err(StatusCode)` if an error occurs during checking pub async fn is_content_binary( item_service: &AsyncItemService, item_id: i64, diff --git a/src/filter_plugin/head.rs b/src/filter_plugin/head.rs index 6ec2ac8..651fb3a 100644 --- a/src/filter_plugin/head.rs +++ b/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` representing a clone of this filter. + /// * `Box` - A new boxed clone of this filter fn clone_box(&self) -> Box { 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` - A vector describing the filter's configurable parameters fn options(&self) -> Vec { 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` representing a clone of this filter. + /// * `Box` - A new boxed clone of this filter fn clone_box(&self) -> Box { 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` - A vector describing the filter's configurable parameters fn options(&self) -> Vec { vec![ FilterOption { diff --git a/src/filter_plugin/utils.rs b/src/filter_plugin/utils.rs index 561dc93..cc20ae1 100644 --- a/src/filter_plugin/utils.rs +++ b/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>` - 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> { super::parse_filter_string(filter_str).map(Some) } @@ -17,11 +20,13 @@ pub fn create_filter_chain(filter_str: &str) -> Result` - 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(s: &str) -> Result { s.parse::() .map_err(|_| std::io::Error::new(std::io::ErrorKind::InvalidInput, "Invalid number"))