docs: Add Rustdoc comments for various structs and functions

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

src/services/async_item_service.rs

@@ -1,3 +1,7 @@
+/// Asynchronous service wrapper for `ItemService`.
+///
+/// Uses `tokio::task::spawn_blocking` to offload synchronous operations (DB/FS)
+/// to a blocking thread pool, allowing non-blocking async usage in servers.
 use crate::common::PIPESIZE;
 use crate::config::Settings;
 use crate::services::error::CoreError;
@@ -15,6 +19,7 @@ use tokio::sync::Mutex;
 /// It uses `tokio::task::spawn_blocking` to run synchronous database and filesystem operations
 /// on a dedicated thread pool, preventing them from blocking the async runtime.
 #[allow(dead_code)]
+/// Async wrapper for ItemService operations.
 pub struct AsyncItemService {
     pub data_dir: PathBuf,
     db: Arc<Mutex<Connection>>,
@@ -25,6 +30,19 @@ pub struct AsyncItemService {
 
 #[allow(dead_code)]
 impl AsyncItemService {
+    /// Creates a new `AsyncItemService`.
+    ///
+    /// # Arguments
+    ///
+    /// * `data_dir` - Path to data directory.
+    /// * `db` - Arc-wrapped mutex for DB connection.
+    /// * `item_service` - Arc-wrapped ItemService.
+    /// * `cmd` - Arc-wrapped mutex for Clap command.
+    /// * `settings` - Arc-wrapped settings.
+    ///
+    /// # Returns
+    ///
+    /// A new `AsyncItemService`.
     pub fn new(
         data_dir: PathBuf, 
         db: Arc<Mutex<Connection>>, 
@@ -41,6 +59,22 @@ impl AsyncItemService {
         }
     }
 
+    /// Internal helper to execute synchronous operations in a blocking task.
+    ///
+    /// Spawns a blocking task with the DB connection and ItemService.
+    ///
+    /// # Type Parameters
+    ///
+    /// * `F` - Closure type.
+    /// * `T` - Return type.
+    ///
+    /// # Arguments
+    ///
+    /// * `f` - The synchronous closure to execute.
+    ///
+    /// # Returns
+    ///
+    /// Result of the closure, or CoreError on task failure.
     async fn execute_blocking<F, T>(&self, f: F) -> Result<T, CoreError>
     where
         F: FnOnce(&Connection, &ItemService) -> Result<T, CoreError> + Send + 'static,