document api functions

src/api/query.rs

@@ -1,3 +1,5 @@
+//! Query endpoint handlers and response types.
+
 use std::sync::Arc;
 
 use axum::{
@@ -14,6 +16,7 @@ use crate::{http_error, query, storage::DocumentMatch};
 
 const MAX_LIMIT: usize = 10;
 
+/// Errors that occur during query processing.
 #[derive(Debug, Snafu)]
 pub enum QueryError {
     #[snafu(display("'limit' query parameter must be a positive integer <= {MAX_LIMIT}."))]
@@ -33,15 +36,21 @@ impl HttpStatus for QueryError {
 
 http_error!(QueryError);
 
+/// Query parameters for search requests.
 #[derive(Deserialize)]
 pub struct QueryParams {
+    /// Maximum number of results to return.
     pub limit: Option<usize>,
 }
 
+/// Response format for successful query requests.
 #[derive(Debug, Serialize, ToSchema)]
 pub struct QueryResponse {
+    /// List of matching document chunks.
     pub results: Vec<DocumentResult>,
+    /// Total number of results returned.
     pub count: usize,
+    /// Original query text that was searched.
     pub query: String,
 }
 
@@ -58,10 +67,14 @@ impl From<(Vec<DocumentMatch>, String)> for QueryResponse {
     }
 }
 
+/// A single document search result.
 #[derive(Debug, Serialize, ToSchema)]
 pub struct DocumentResult {
+    /// Calibre book ID containing this text.
     pub book_id: i64,
+    /// Text content of the matching chunk.
     pub text_chunk: String,
+    /// Similarity score between 0.0 and 1.0.
     pub similarity: f64,
 }
 
@@ -75,6 +88,7 @@ impl From<DocumentMatch> for DocumentResult {
     }
 }
 
+/// Execute a semantic search query against the document database.
 #[utoipa::path(
     post,
     path = "/query",