docs: Add Rustdoc comments to CompressionService methods

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

src/modes/server/common.rs

@@ -55,6 +55,22 @@ pub struct ServerConfig {
 /// This struct encapsulates the shared state that is accessible to all request handlers,
 /// including database connections, file paths, services, and configuration.
 #[derive(Clone)]
+/// Application state shared across all routes.
+///
+/// This struct encapsulates the shared state that is accessible to all request handlers,
+/// including database connections, file paths, services, and configuration.
+///
+/// # Examples
+///
+/// ```
+/// let state = AppState {
+///     db: Arc::new(Mutex::new(conn)),
+///     data_dir: PathBuf::from("/data"),
+///     item_service: Arc::new(ItemService::new(data_dir.clone())),
+///     cmd: Arc::new(Mutex::new(Command::new("keep"))),
+///     settings: Arc::new(settings),
+/// };
+/// ```
 pub struct AppState {
     /// Database connection wrapped in Arc<Mutex>.
     ///
@@ -84,6 +100,24 @@ pub struct AppState {
 /// This generic type is used for all API responses to provide a consistent structure across
 /// different endpoints.
 #[derive(Debug, Serialize, Deserialize, ToSchema)]
+/// Standard API response wrapper containing success status, data payload, and error information.
+///
+/// This generic type is used for all API responses to provide a consistent structure across
+/// different endpoints.
+///
+/// # Type Parameters
+///
+/// * `T` - The type of the data payload.
+///
+/// # Examples
+///
+/// ```
+/// let response: ApiResponse<Vec<ItemInfo>> = ApiResponse {
+///     success: true,
+///     data: Some(items),
+///     error: None,
+/// };
+/// ```
 #[schema(description = "Standard API response wrapper containing success status, data payload, and error information")]
 pub struct ApiResponse<T> {
     /// Success indicator.
@@ -104,6 +138,19 @@ pub struct ApiResponse<T> {
 ///
 /// Specialized response for endpoints that return multiple items.
 #[derive(Serialize, Deserialize, ToSchema)]
+/// Response type for list of item information.
+///
+/// Specialized response for endpoints that return multiple items.
+///
+/// # Examples
+///
+/// ```
+/// let response = ItemInfoListResponse {
+///     success: true,
+///     data: Some(vec![item_info]),
+///     error: None,
+/// };
+/// ```
 pub struct ItemInfoListResponse {
     /// Success indicator.
     ///
@@ -123,6 +170,19 @@ pub struct ItemInfoListResponse {
 ///
 /// Specialized response for endpoints that return a single item's details.
 #[derive(Serialize, Deserialize, ToSchema)]
+/// Response type for single item information.
+///
+/// Specialized response for endpoints that return a single item's details.
+///
+/// # Examples
+///
+/// ```
+/// let response = ItemInfoResponse {
+///     success: true,
+///     data: Some(item_info),
+///     error: None,
+/// };
+/// ```
 pub struct ItemInfoResponse {
     /// Success indicator.
     ///
@@ -142,6 +202,19 @@ pub struct ItemInfoResponse {
 ///
 /// Specialized response for endpoints that return item content and related metadata.
 #[derive(Serialize, Deserialize, ToSchema)]
+/// Response type for item content information.
+///
+/// Specialized response for endpoints that return item content and related metadata.
+///
+/// # Examples
+///
+/// ```
+/// let response = ItemContentInfoResponse {
+///     success: true,
+///     data: Some(content_info),
+///     error: None,
+/// };
+/// ```
 pub struct ItemContentInfoResponse {
     /// Success indicator.
     ///
@@ -161,6 +234,19 @@ pub struct ItemContentInfoResponse {
 ///
 /// Specialized response for metadata-only endpoints.
 #[derive(Serialize, Deserialize, ToSchema)]
+/// Response type for metadata.
+///
+/// Specialized response for metadata-only endpoints.
+///
+/// # Examples
+///
+/// ```
+/// let response = MetadataResponse {
+///     success: true,
+///     data: Some(meta_map),
+///     error: None,
+/// };
+/// ```
 pub struct MetadataResponse {
     /// Success indicator.
     ///
@@ -180,6 +266,19 @@ pub struct MetadataResponse {
 ///
 /// Specialized response for system status endpoints.
 #[derive(Serialize, Deserialize, ToSchema)]
+/// Response type for status information.
+///
+/// Specialized response for system status endpoints.
+///
+/// # Examples
+///
+/// ```
+/// let response = StatusInfoResponse {
+///     success: true,
+///     data: Some(status_info),
+///     error: None,
+/// };
+/// ```
 pub struct StatusInfoResponse {
     /// Success indicator.
     ///
@@ -200,6 +299,23 @@ pub struct StatusInfoResponse {
 /// This structure represents the full details of an item, combining basic item
 /// properties with associated tags and metadata.
 #[derive(Serialize, Deserialize, ToSchema)]
+/// Complete information about a stored item including metadata and tags.
+///
+/// This structure represents the full details of an item, combining basic item
+/// properties with associated tags and metadata.
+///
+/// # Examples
+///
+/// ```
+/// let item_info = ItemInfo {
+///     id: 42,
+///     ts: "2023-12-01T15:30:45Z".to_string(),
+///     size: Some(1024),
+///     compression: "gzip".to_string(),
+///     tags: vec!["important".to_string()],
+///     metadata: HashMap::from([("mime_type".to_string(), "text/plain".to_string())]),
+/// };
+/// ```
 #[schema(description = "Complete information about a stored item including metadata and tags")]
 pub struct ItemInfo {
     /// Item ID.
@@ -245,6 +361,20 @@ pub struct ItemInfo {
 /// * `content` - Optional string content (text only).
 /// * `binary` - True if binary content.
 #[derive(Serialize, Deserialize, ToSchema)]
+/// Item information including content and metadata, with binary detection.
+///
+/// This structure provides item details along with its content, handling binary
+/// content detection and safe string representation.
+///
+/// # Examples
+///
+/// ```
+/// let content_info = ItemContentInfo {
+///     metadata: HashMap::from([("mime_type".to_string(), "text/plain".to_string())]),
+///     content: Some("Hello, world!".to_string()),
+///     binary: false,
+/// };
+/// ```
 #[schema(description = "Item information including content and metadata, with binary detection")]
 pub struct ItemContentInfo {
     /// Metadata hashmap.
@@ -273,6 +403,15 @@ pub struct ItemContentInfo {
 ///
 /// * `tags` - Optional comma-separated tags for filtering.
 #[derive(Debug, Deserialize)]
+/// Query parameters for tags.
+///
+/// Structure for handling tag-based query parameters in API requests.
+///
+/// # Examples
+///
+/// ```
+/// let query = TagsQuery { tags: Some("tag1,tag2".to_string()) };
+/// ```
 pub struct TagsQuery {
     /// Optional comma-separated tags.
     ///
@@ -291,6 +430,20 @@ pub struct TagsQuery {
 /// * `start` - Optional start index.
 /// * `count` - Optional item limit.
 #[derive(Debug, Deserialize)]
+/// Query parameters for listing items.
+///
+/// Structure for pagination and sorting parameters in item listing endpoints.
+///
+/// # Examples
+///
+/// ```
+/// let query = ListItemsQuery {
+///     tags: Some("important".to_string()),
+///     order: Some("newest".to_string()),
+///     start: Some(0),
+///     count: Some(10),
+/// };
+/// ```
 pub struct ListItemsQuery {
     /// Optional comma-separated tags for filtering.
     ///
@@ -322,6 +475,21 @@ pub struct ListItemsQuery {
 /// * `stream` - Enable streaming (default false).
 /// * `as_meta` - Return as JSON metadata (default false).
 #[derive(Debug, Deserialize, utoipa::ToSchema)]
+/// Query parameters for item retrieval.
+///
+/// Structure for content retrieval parameters, including binary handling and streaming options.
+///
+/// # Examples
+///
+/// ```
+/// let query = ItemQuery {
+///     allow_binary: true,
+///     offset: 0,
+///     length: 1024,
+///     stream: false,
+///     as_meta: false,
+/// };
+/// ```
 pub struct ItemQuery {
     /// Allow binary content (default: true).
     ///
@@ -363,6 +531,22 @@ pub struct ItemQuery {
 /// * `stream` - Enable streaming (default false).
 /// * `as_meta` - Return as JSON metadata (default false).
 #[derive(Debug, Deserialize, utoipa::ToSchema)]
+/// Query parameters for item content retrieval.
+///
+/// Extended query parameters for content-specific operations, including tag filtering.
+///
+/// # Examples
+///
+/// ```
+/// let query = ItemContentQuery {
+///     tags: Some("important".to_string()),
+///     allow_binary: true,
+///     offset: 0,
+///     length: 1024,
+///     stream: false,
+///     as_meta: false,
+/// };
+/// ```
 pub struct ItemContentQuery {
     /// Optional comma-separated tags for filtering.
     ///