docs: Add comprehensive Rustdoc comments to public APIs

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

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.
-/// * `request` - The incoming HTTP request.
-/// * `next` - The next middleware in the chain.
+/// * `ConnectInfo(addr)` - Connection info with client address.
+/// * `request` - Incoming request.
+/// * `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_hash` - Optional hashed password for authentication.
+/// * `password` - Optional plain text password.
+/// * `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>,