docs: Add rustdoc to db.rs functions for arguments and returns

Co-authored-by: aider (openai/andrew/openrouter/deepseek/deepseek-chat-v3.1) <aider@aider.chat>

src/db.rs

@@ -185,6 +185,16 @@ pub fn add_meta(conn: &Connection, item_id: i64, name: &str, value: &str) -> Res
     store_meta(conn, meta)
 }
 
+/// Updates an existing item in the database
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+/// * `item` - Item with updated values
+///
+/// # Returns
+///
+/// * `Result<()>` - Success or error if the operation fails
 pub fn update_item(conn: &Connection, item: Item) -> Result<()> {
     debug!("DB: Updating item: {:?}", item);
     conn.execute(
@@ -198,12 +208,32 @@ pub fn update_item(conn: &Connection, item: Item) -> Result<()> {
     Ok(())
 }
 
+/// Deletes an item from the database
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+/// * `item` - Item to delete
+///
+/// # Returns
+///
+/// * `Result<()>` - Success or error if the operation fails
 pub fn delete_item(conn: &Connection, item: Item) -> Result<()> {
     debug!("DB: Deleting item: {:?}", item);
     conn.execute("DELETE FROM items WHERE id=?1", params![item.id])?;
     Ok(())
 }
 
+/// Deletes a metadata entry from the database
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+/// * `meta` - Metadata entry to delete
+///
+/// # Returns
+///
+/// * `Result<()>` - Success or error if the operation fails
 pub fn query_delete_meta(conn: &Connection, meta: Meta) -> Result<()> {
     debug!("DB: Deleting meta: {:?}", meta);
     conn.execute(
@@ -213,6 +243,16 @@ pub fn query_delete_meta(conn: &Connection, meta: Meta) -> Result<()> {
     Ok(())
 }
 
+/// Inserts or updates a metadata entry in the database
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+/// * `meta` - Metadata entry to upsert
+///
+/// # Returns
+///
+/// * `Result<()>` - Success or error if the operation fails
 pub fn query_upsert_meta(conn: &Connection, meta: Meta) -> Result<()> {
     debug!("DB: Inserting meta: {:?}", meta);
     conn.execute(
@@ -223,6 +263,16 @@ pub fn query_upsert_meta(conn: &Connection, meta: Meta) -> Result<()> {
     Ok(())
 }
 
+/// Stores a metadata entry, deleting it if the value is empty
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+/// * `meta` - Metadata entry to store
+///
+/// # Returns
+///
+/// * `Result<()>` - Success or error if the operation fails
 pub fn store_meta(conn: &Connection, meta: Meta) -> Result<()> {
     if meta.value.is_empty() {
         query_delete_meta(conn, meta)?;
@@ -232,6 +282,16 @@ pub fn store_meta(conn: &Connection, meta: Meta) -> Result<()> {
     Ok(())
 }
 
+/// Inserts a tag into the database
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+/// * `tag` - Tag to insert
+///
+/// # Returns
+///
+/// * `Result<()>` - Success or error if the operation fails
 pub fn insert_tag(conn: &Connection, tag: Tag) -> Result<()> {
     debug!("DB: Inserting tag: {:?}", tag);
     conn.execute(
@@ -241,12 +301,33 @@ pub fn insert_tag(conn: &Connection, tag: Tag) -> Result<()> {
     Ok(())
 }
 
+/// Deletes all tags associated with an item
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+/// * `item` - Item whose tags should be deleted
+///
+/// # Returns
+///
+/// * `Result<()>` - Success or error if the operation fails
 pub fn delete_item_tags(conn: &Connection, item: Item) -> Result<()> {
     debug!("DB: Deleting all item tags: {:?}", item);
     conn.execute("DELETE FROM tags WHERE id=?1", params![item.id])?;
     Ok(())
 }
 
+/// Sets the tags for an item, replacing any existing tags
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+/// * `item` - Item to set tags for
+/// * `tags` - Vector of tag names to set
+///
+/// # Returns
+///
+/// * `Result<()>` - Success or error if the operation fails
 pub fn set_item_tags(conn: &Connection, item: Item, tags: &Vec<String>) -> Result<()> {
     debug!("DB: Setting tags for item: {:?} ?{:?}", item, tags);
     delete_item_tags(conn, item.clone())?;
@@ -264,6 +345,15 @@ pub fn set_item_tags(conn: &Connection, item: Item, tags: &Vec<String>) -> Resul
     Ok(())
 }
 
+/// Queries all items from the database, ordered by ID
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+///
+/// # Returns
+///
+/// * `Result<Vec<Item>>` - All items in the database or an error
 pub fn query_all_items(conn: &Connection) -> Result<Vec<Item>> {
     debug!("DB: Querying all items");
     let mut statement = conn
@@ -285,6 +375,16 @@ pub fn query_all_items(conn: &Connection) -> Result<Vec<Item>> {
     Ok(items)
 }
 
+/// Queries items that have all the specified tags
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+/// * `tags` - Vector of tag names to match
+///
+/// # Returns
+///
+/// * `Result<Vec<Item>>` - Matching items or an error
 pub fn query_tagged_items<'a>(conn: &'a Connection, tags: &'a Vec<String>) -> Result<Vec<Item>> {
     debug!("DB: Querying tagged items: {:?}", tags);
     let mut statement = conn
@@ -327,11 +427,31 @@ pub fn query_tagged_items<'a>(conn: &'a Connection, tags: &'a Vec<String>) -> Re
     Ok(items)
 }
 
+/// Gets all items from the database
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+///
+/// # Returns
+///
+/// * `Result<Vec<Item>>` - All items or an error
 pub fn get_items(conn: &Connection) -> Result<Vec<Item>> {
     debug!("DB: Getting all items");
     query_all_items(conn)
 }
 
+/// Gets items matching specified tags and metadata criteria
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+/// * `tags` - Vector of tag names to match
+/// * `meta` - HashMap of metadata key-value pairs to match
+///
+/// # Returns
+///
+/// * `Result<Vec<Item>>` - Matching items or an error
 pub fn get_items_matching(
     conn: &Connection,
     tags: &Vec<String>,
@@ -381,6 +501,17 @@ pub fn get_items_matching(
     }
 }
 
+/// Gets a single item matching specified tags
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+/// * `tags` - Vector of tag names to match
+/// * `_meta` - Unused metadata parameter
+///
+/// # Returns
+///
+/// * `Result<Option<Item>>` - The matching item or None if not found, or an error
 pub fn get_item_matching(
     conn: &Connection,
     tags: &Vec<String>,
@@ -425,6 +556,16 @@ pub fn get_item_matching(
     }
 }
 
+/// Gets an item by its ID
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+/// * `item_id` - ID of the item to retrieve
+///
+/// # Returns
+///
+/// * `Result<Option<Item>>` - The item if found, None if not found, or an error
 pub fn get_item(conn: &Connection, item_id: i64) -> Result<Option<Item>> {
     debug!("DB: Getting item {:?}", item_id);
     let mut statement = conn
@@ -449,6 +590,15 @@ pub fn get_item(conn: &Connection, item_id: i64) -> Result<Option<Item>> {
     }
 }
 
+/// Gets the most recently created item
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+///
+/// # Returns
+///
+/// * `Result<Option<Item>>` - The most recent item or None if no items exist, or an error
 pub fn get_item_last(conn: &Connection) -> Result<Option<Item>> {
     debug!("DB: Getting last item");
     let mut statement = conn
@@ -474,6 +624,16 @@ pub fn get_item_last(conn: &Connection) -> Result<Option<Item>> {
     }
 }
 
+/// Gets all tags for a specific item
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+/// * `item` - Item to get tags for
+///
+/// # Returns
+///
+/// * `Result<Vec<Tag>>` - The item's tags or an error
 pub fn get_item_tags(conn: &Connection, item: &Item) -> Result<Vec<Tag>> {
     debug!("DB: Getting tags for item: {:?}", item);
     let mut statement = conn
@@ -493,6 +653,16 @@ pub fn get_item_tags(conn: &Connection, item: &Item) -> Result<Vec<Tag>> {
     Ok(tags)
 }
 
+/// Gets all metadata for a specific item
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+/// * `item` - Item to get metadata for
+///
+/// # Returns
+///
+/// * `Result<Vec<Meta>>` - The item's metadata or an error
 pub fn get_item_meta(conn: &Connection, item: &Item) -> Result<Vec<Meta>> {
     debug!("DB: Getting item meta: {:?}", item);
     let mut statement = conn
@@ -513,6 +683,17 @@ pub fn get_item_meta(conn: &Connection, item: &Item) -> Result<Vec<Meta>> {
     Ok(metas)
 }
 
+/// Gets a specific metadata entry for an item by name
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+/// * `item` - Item to get metadata for
+/// * `name` - Name of the metadata field
+///
+/// # Returns
+///
+/// * `Result<Option<Meta>>` - The metadata entry if found, None if not found, or an error
 pub fn get_item_meta_name(conn: &Connection, item: &Item, name: String) -> Result<Option<Meta>> {
     debug!("DB: Getting item meta name: {:?} {:?}", item, name);
     let mut statement = conn
@@ -530,6 +711,17 @@ pub fn get_item_meta_name(conn: &Connection, item: &Item, name: String) -> Resul
     }
 }
 
+/// Gets the value of a specific metadata field for an item
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+/// * `item` - Item to get metadata for
+/// * `name` - Name of the metadata field
+///
+/// # Returns
+///
+/// * `Result<Option<String>>` - The metadata value if found, None if not found, or an error
 pub fn get_item_meta_value(conn: &Connection, item: &Item, name: String) -> Result<Option<String>> {
     debug!("DB: Getting item meta value: {:?} {:?}", item, name);
     let mut statement = conn
@@ -543,6 +735,16 @@ pub fn get_item_meta_value(conn: &Connection, item: &Item, name: String) -> Resu
     }
 }
 
+/// Gets tags for multiple items in a single query
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+/// * `item_ids` - Slice of item IDs to get tags for
+///
+/// # Returns
+///
+/// * `Result<HashMap<i64, Vec<Tag>>>` - Mapping of item IDs to their tags, or an error
 pub fn get_tags_for_items(conn: &Connection, item_ids: &[i64]) -> Result<std::collections::HashMap<i64, Vec<Tag>>> {
     debug!("DB: Getting tags for items: {:?}", item_ids);
     
@@ -574,6 +776,16 @@ pub fn get_tags_for_items(conn: &Connection, item_ids: &[i64]) -> Result<std::co
     Ok(tags_map)
 }
 
+/// Gets metadata for multiple items in a single query
+///
+/// # Arguments
+///
+/// * `conn` - Database connection
+/// * `item_ids` - Slice of item IDs to get metadata for
+///
+/// # Returns
+///
+/// * `Result<HashMap<i64, HashMap<String, String>>>` - Mapping of item IDs to their metadata, or an error
 pub fn get_meta_for_items(conn: &Connection, item_ids: &[i64]) -> Result<std::collections::HashMap<i64, std::collections::HashMap<String, String>>> {
     debug!("DB: Getting meta for items: {:?}", item_ids);