docs: Add comprehensive Rustdoc comments to public APIs

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

src/filter_plugin/mod.rs

@@ -2,6 +2,20 @@ use std::io::{Result, Read, Write};
 use std::str::FromStr;
 use strum::EnumString;
 
+/// Filter plugin module for processing input streams.
+///
+/// This module defines the `FilterPlugin` trait and `FilterChain` for chaining filters,
+/// along with parsing utilities for filter strings. Filters can process data like head/tail,
+/// grep, etc.
+///
+/// # Usage
+///
+/// Parse a filter string and apply to a reader:
+///
+/// ```
+/// let chain = parse_filter_string("head_lines(10)|grep(pattern=error)")?;
+/// chain.filter(&mut reader, &mut writer)?;
+/// ```
 pub mod head;
 pub mod tail;
 pub mod skip;
@@ -18,6 +32,14 @@ pub use grep::GrepFilter;
 pub use strip_ansi::StripAnsiFilter;
 
 /// Represents an option for a filter plugin.
+///
+/// Defines a configurable parameter for filters, with name, default, and required flag.
+///
+/// # Fields
+///
+/// * `name` - Option name.
+/// * `default` - Optional default value.
+/// * `required` - If true, must be provided.
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize, utoipa::ToSchema)]
 pub struct FilterOption {
     pub name: String,
@@ -27,6 +49,25 @@ pub struct FilterOption {
 }
 
 /// Trait for filter plugins that process input streams.
+///
+/// Implement this trait to create a filter that reads from an input stream and writes filtered output.
+///
+/// # Required Methods
+///
+/// * `filter` - Process the stream.
+/// * `clone_box` - For cloning dynamic instances.
+/// * `options` - Describe configurable options.
+///
+/// # Examples
+///
+/// ```
+/// impl FilterPlugin for MyFilter {
+///     fn filter(&mut self, reader: Box<&mut dyn Read>, writer: Box<&mut dyn Write>) -> Result<()> {
+///         // Implementation
+///     }
+///     // ...
+/// }
+/// ```
 pub trait FilterPlugin: Send {
     /// Processes the input stream and writes the filtered output.
     ///
@@ -54,6 +95,14 @@ pub trait FilterPlugin: Send {
 }
 
 /// Enum representing the different types of filters.
+///
+/// Used for parsing and instantiating specific filter plugins.
+///
+/// # Variants
+///
+/// * `HeadBytes` - Head by bytes.
+/// * `HeadLines` - Head by lines.
+/// * ... etc.
 #[derive(Debug, EnumString, strum::VariantNames, strum::Display)]
 #[strum(serialize_all = "snake_case")]
 pub enum FilterType {
@@ -68,6 +117,12 @@ pub enum FilterType {
 }
 
 /// A chain of filter plugins applied sequentially.
+///
+/// Chains multiple filters, applying them in order to the input stream.
+///
+/// # Fields
+///
+/// * `plugins` - Vector of boxed filter plugins.
 pub struct FilterChain {
     plugins: Vec<Box<dyn FilterPlugin>>,
 }

src/modes/server/common.rs

@@ -238,6 +238,12 @@ pub struct ItemInfo {
 ///
 /// This structure provides item details along with its content, handling binary
 /// content detection and safe string representation.
+///
+/// # Fields
+///
+/// * `metadata` - Flattened metadata HashMap.
+/// * `content` - Optional string content (text only).
+/// * `binary` - True if binary content.
 #[derive(Serialize, Deserialize, ToSchema)]
 #[schema(description = "Item information including content and metadata, with binary detection")]
 pub struct ItemContentInfo {
@@ -262,6 +268,10 @@ pub struct ItemContentInfo {
 /// Query parameters for tags.
 ///
 /// Structure for handling tag-based query parameters in API requests.
+///
+/// # Fields
+///
+/// * `tags` - Optional comma-separated tags for filtering.
 #[derive(Debug, Deserialize)]
 pub struct TagsQuery {
     /// Optional comma-separated tags.
@@ -273,6 +283,13 @@ pub struct TagsQuery {
 /// Query parameters for listing items.
 ///
 /// Structure for pagination and sorting parameters in item listing endpoints.
+///
+/// # Fields
+///
+/// * `tags` - Optional tags for filtering.
+/// * `order` - Optional sort: "newest" or "oldest".
+/// * `start` - Optional start index.
+/// * `count` - Optional item limit.
 #[derive(Debug, Deserialize)]
 pub struct ListItemsQuery {
     /// Optional comma-separated tags for filtering.
@@ -296,6 +313,14 @@ pub struct ListItemsQuery {
 /// Query parameters for item retrieval.
 ///
 /// Structure for content retrieval parameters, including binary handling and streaming options.
+///
+/// # Fields
+///
+/// * `allow_binary` - Allow binary (default true).
+/// * `offset` - Byte offset (default 0).
+/// * `length` - Byte length (default 0 = all).
+/// * `stream` - Enable streaming (default false).
+/// * `as_meta` - Return as JSON metadata (default false).
 #[derive(Debug, Deserialize, utoipa::ToSchema)]
 pub struct ItemQuery {
     /// Allow binary content (default: true).
@@ -328,6 +353,15 @@ pub struct ItemQuery {
 /// Query parameters for item content retrieval.
 ///
 /// Extended query parameters for content-specific operations, including tag filtering.
+///
+/// # Fields
+///
+/// * `tags` - Optional tags for filtering.
+/// * `allow_binary` - Allow binary (default true).
+/// * `offset` - Byte offset (default 0).
+/// * `length` - Byte length (default 0 = all).
+/// * `stream` - Enable streaming (default false).
+/// * `as_meta` - Return as JSON metadata (default false).
 #[derive(Debug, Deserialize, utoipa::ToSchema)]
 pub struct ItemContentQuery {
     /// Optional comma-separated tags for filtering.
@@ -401,7 +435,12 @@ fn default_as_meta() -> bool {
 ///
 /// # Returns
 ///
-/// * `bool` - True if authentication succeeds, false otherwise.
+/// * `true` - If authentication succeeds.
+/// * `false` - Otherwise.
+///
+/// # Errors
+///
+/// None; returns false on failure.
 fn check_bearer_auth(auth_str: &str, expected_password: &str, expected_hash: &Option<String>) -> bool {
     if !auth_str.starts_with("Bearer ") {
         return false;
@@ -431,7 +470,12 @@ fn check_bearer_auth(auth_str: &str, expected_password: &str, expected_hash: &Op
 ///
 /// # Returns
 ///
-/// * `bool` - True if authentication succeeds, false otherwise.
+/// * `true` - If authentication succeeds.
+/// * `false` - Otherwise.
+///
+/// # Errors
+///
+/// Returns false on decode or validation failure.
 fn check_basic_auth(auth_str: &str, expected_password: &str, expected_hash: &Option<String>) -> bool {
     if !auth_str.starts_with("Basic ") {
         return false;
@@ -470,7 +514,16 @@ fn check_basic_auth(auth_str: &str, expected_password: &str, expected_hash: &Opt
 ///
 /// # Returns
 ///
-/// * `bool` - True if authorization is valid, false otherwise.
+/// * `true` - If authorized (or no auth required).
+/// * `false` - If unauthorized.
+///
+/// # Examples
+///
+/// ```
+/// if check_auth(&headers, &Some("pass".to_string()), &None) {
+///     // Proceed
+/// }
+/// ```
 pub fn check_auth(headers: &HeaderMap, password: &Option<String>, password_hash: &Option<String>) -> bool {
     // If neither password nor hash is set, no authentication required
     if password.is_none() && password_hash.is_none() {
@@ -493,13 +546,17 @@ pub fn check_auth(headers: &HeaderMap, password: &Option<String>, password_hash:
 ///
 /// # Arguments
 ///
-/// * `ConnectInfo(addr)` - Connection information including client address.
+/// * `ConnectInfo(addr)` - Connection info with client address.
-/// * `request` - The incoming HTTP request.
+/// * `request` - Incoming request.
-/// * `next` - The next middleware in the chain.
+/// * `next` - Next middleware.
 ///
 /// # Returns
 ///
-/// The response with logging applied.
+/// The processed response with logging.
+///
+/// # Examples
+///
+/// Used in Axum router: `.layer_handler(logging_middleware)`.
 pub async fn logging_middleware(
     ConnectInfo(addr): ConnectInfo<SocketAddr>,
     request: Request,
@@ -540,12 +597,19 @@ pub async fn logging_middleware(
 ///
 /// # Arguments
 ///
-/// * `password` - Optional plain text password for authentication.
+/// * `password` - Optional plain text password.
-/// * `password_hash` - Optional hashed password for authentication.
+/// * `password_hash` - Optional hashed password.
 ///
 /// # Returns
 ///
-/// An authentication middleware function that can be used with axum.
+/// A clonable async middleware function for Axum.
+///
+/// # Examples
+///
+/// ```
+/// let auth_middleware = create_auth_middleware(Some("pass".to_string()), None);
+/// router.layer(auth_middleware);
+/// ```
 pub fn create_auth_middleware(
     password: Option<String>,
     password_hash: Option<String>,