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,

src/services/meta_service.rs

@@ -142,6 +142,21 @@ impl MetaService {
         }
     }
 
+    /// Internal helper to process a meta plugin response and store metadata.
+    ///
+    /// Iterates over the metadata entries in the response and stores each in the database
+    /// using `store_meta`. Logs warnings if storage fails.
+    ///
+    /// # Arguments
+    ///
+    /// * `conn` - Database connection.
+    /// * `item_id` - Item ID to associate with the metadata.
+    /// * `_plugin` - Reference to the plugin (unused).
+    /// * `response` - The plugin response containing metadata.
+    ///
+    /// # Errors
+    ///
+    /// Logs warnings for individual storage failures but does not return errors.
     fn process_plugin_response(
         &self,
         conn: &Connection,
@@ -163,6 +178,21 @@ impl MetaService {
         }
     }
 
+    /// Collects initial metadata from environment variables and hostname.
+    ///
+    /// Gathers metadata from `KEEP_META_*` environment variables and adds hostname
+    /// if not already present.
+    ///
+    /// # Returns
+    ///
+    /// A `HashMap` of initial metadata key-value pairs.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let service = MetaService::new();
+    /// let initial_meta = service.collect_initial_meta();
+    /// ```
     pub fn collect_initial_meta(&self) -> HashMap<String, String> {
         let mut item_meta: HashMap<String, String> = crate::modes::common::get_meta_from_env();
 
@@ -176,6 +206,11 @@ impl MetaService {
 }
 
 impl Default for MetaService {
+    /// Provides a default `MetaService` instance.
+    ///
+    /// # Returns
+    ///
+    /// A new `MetaService` via `new()`.
     fn default() -> Self {
         Self::new()
     }