doc: update documentation to reach higher coverage

01.workspace/heave/src/imp/catalog_contains_key.rs

@@ -1,6 +1,21 @@
 use crate::*;
 
 impl Catalog {
+    /// Checks if the catalog contains an entity with the specified key.
+    ///
+    /// # Arguments
+    ///
+    /// * `k` - The key to check for.
+    ///
+    /// # Returns
+    ///
+    /// `Ok(true)` if an entity with the specified key exists in the catalog,
+    /// `Ok(false)` otherwise.
+    ///
+    /// # Errors
+    ///
+    /// Returns `Err(FailedTo::LockCatalog)` if the catalog's internal mutex
+    /// could not be locked.
     pub fn contains_key(&self, k: &str) -> Result<bool, FailedTo> {
         self.with_items(|items| Ok(items.contains_key(k)))
     }

01.workspace/heave/src/imp/catalog_is_empty.rs

@@ -1,6 +1,16 @@
 use crate::*;
 
 impl Catalog {
+    /// Checks if the catalog is empty.
+    ///
+    /// # Returns
+    ///
+    /// `Ok(true)` if the catalog contains no entities, `Ok(false)` otherwise.
+    ///
+    /// # Errors
+    ///
+    /// Returns `Err(FailedTo::LockCatalog)` if the catalog's internal mutex
+    /// could not be locked.
     pub fn is_empty(&self) -> Result<bool, FailedTo> {
         self.with_items(|items| Ok(items.is_empty()))
     }

01.workspace/heave/src/imp/catalog_len.rs

@@ -1,6 +1,16 @@
 use crate::*;
 
 impl Catalog {
+    /// Returns the number of entities in the catalog.
+    ///
+    /// # Returns
+    ///
+    /// The total number of entities currently held in the catalog's memory.
+    ///
+    /// # Errors
+    ///
+    /// Returns `Err(FailedTo::LockCatalog)` if the catalog's internal mutex
+    /// could not be locked.
     pub fn len(&self) -> Result<usize, FailedTo> {
         self.with_items(|items| Ok(items.len()))
     }

01.workspace/heave/src/imp/catalog_list_by_class.rs

@@ -1,13 +1,25 @@
 use crate::*;
 
 impl Catalog {
-    /// Returns an iterator over all entities of a specific class in the in-memory catalog.
+    /// Returns a list of all entities of a specific class from the in-memory catalog.
     ///
-    /// This is a purely in-memory operation and does not interact with the database.
+    /// This method filters the in-memory entities by the class of type `T` and
+    /// attempts to convert them into `T`. This is a purely in-memory operation
+    /// and does not interact with the database.
     ///
     /// # Returns
     ///
-    /// An iterator that yields items of type `T` from the in-memory cache.
+    /// A `Result` containing a `Vec` of `Result<T, FailedTo>>`. Each inner `Result`
+    /// represents the outcome of converting an entity to type `T`.
+    ///
+    /// - `Ok(Vec<Ok(T)>)`: A vector of successfully converted entities.
+    /// - `Ok(Vec<Err(FailedTo::ConvertEntity)>)`: If an entity of the correct class
+    ///   could not be converted to type `T`.
+    ///
+    /// # Errors
+    ///
+    /// Returns `Err(FailedTo::LockCatalog)` if the catalog's internal mutex
+    /// could not be locked.
     pub fn list_by_class<T>(&self) -> Result<Vec<Result<T, FailedTo>>, FailedTo>
     where
         T: EAV,

01.workspace/heave/src/imp/catalog_list_by_class_and_subclass.rs

@@ -1,14 +1,29 @@
 use crate::*;
 
 impl Catalog {
-    /// Returns an iterator over all entities of a specific class and subclass
-    /// in the in-memory catalog.
+    /// Returns a list of all entities of a specific class and subclass from the in-memory catalog.
     ///
-    /// This is a purely in-memory operation and does not interact with the database.
+    /// This method filters the in-memory entities by the class of type `T` and the
+    /// provided `subclass`, then attempts to convert them into `T`. This is a purely
+    /// in-memory operation and does not interact with the database.
+    ///
+    /// # Arguments
+    ///
+    /// * `subclass` - The subclass to filter by.
     ///
     /// # Returns
     ///
-    /// An iterator that yields items of type `T` from the in-memory cache.
+    /// A `Result` containing a `Vec` of `Result<T, FailedTo>>`. Each inner `Result`
+    /// represents the outcome of converting an entity to type `T`.
+    ///
+    /// - `Ok(Vec<Ok(T)>)`: A vector of successfully converted entities.
+    /// - `Ok(Vec<Err(FailedTo::ConvertEntity)>)`: If an entity of the correct class
+    ///   and subclass could not be converted to type `T`.
+    ///
+    /// # Errors
+    ///
+    /// Returns `Err(FailedTo::LockCatalog)` if the catalog's internal mutex
+    /// could not be locked.
     pub fn list_by_class_and_subclass<T>(
         &self,
         subclass: &str,

01.workspace/heave/src/lib.rs

@@ -1,6 +1,6 @@
 //! A lightweight and intuitive Entity-Attribute-Value (EAV) database library for Rust.
 //!
-//! This library provides a simple way to persist and query semi-structured data using an EAV model on top of a SQLite database. It is designed to be easy to use, with a focus on simplicity and developer experience.
+//! This library provides a simple and thread safe way to persist and query semi-structured data using an EAV model on top of a SQLite database. It is designed to be easy to use, with a focus on simplicity and developer experience.
 //!
 //! ## What is the Entity-Attribute-Value (EAV) Model?
 //!

01.workspace/heave/src/str/attribute.rs

@@ -1,12 +1,26 @@
 use crate::*;
 
+/// Represents an attribute of an entity, consisting of an ID and a `Value`.
 #[derive(Debug, PartialEq, Clone)]
 pub struct O {
+    /// The unique identifier for this attribute (e.g., "name", "price").
     pub id: String,
+    /// The value of the attribute.
     pub value: Value,
 }
 
 impl Attribute {
+    /// Creates a new `Attribute` instance.
+    ///
+    /// # Arguments
+    ///
+    /// * `id` - The ID of the attribute.
+    /// * `value` - The value of the attribute, which can be any type that
+    ///   implements `Into<Value>`.
+    ///
+    /// # Returns
+    ///
+    /// A new `Attribute` instance.
     pub fn new(id: &str, value: impl Into<Value>) -> Self {
         Self {
             id: String::from(id),

01.workspace/heave/src/str/filter.rs

@@ -21,12 +21,22 @@ impl<'a> Filter<'a> {
             conditions: Vec::new(),
         }
     }
-    /// Adds a class condition to the filter.
+    /// Sets the entity class to filter by.
+    ///
+    /// # Arguments
+    ///
+    /// * `value` - The class name to filter for. Only entities with this class
+    ///   name will be considered.
     pub fn with_class(mut self, value: &str) -> Self {
         self.class = Some(value.to_string());
         self
     }
-    /// Adds a subclass condition to the filter.
+    /// Sets the entity subclass to filter by.
+    ///
+    /// # Arguments
+    ///
+    /// * `value` - The subclass name to filter for. Only entities with this
+    ///   subclass name will be considered.
     pub fn with_subclass(mut self, value: &str) -> Self {
         self.subclass = Some(value.to_string());
         self

01.workspace/heave/src/str/sqlite_failed_to.rs

@@ -1,11 +1,20 @@
+/// Represents failures that can occur specifically within the SQLite implementation.
 #[derive(Debug, PartialEq, PartialOrd, Eq, Ord, Clone, Copy, Hash)]
 pub enum FailedTo {
+    /// Failed to begin a database transaction.
     BeginTransaction,
+    /// Failed to build a SQL statement.
     BuildStatement,
+    /// Failed to commit a database transaction.
     CommitTransaction,
+    /// Failed to execute a batch of SQL statements.
     ExecuteBatch,
+    /// Failed to execute a SQL query.
     ExecuteQuery,
+    /// Failed to execute a prepared SQL statement.
     ExecuteStatement,
+    /// Failed to open a connection to the SQLite database.
     OpenConnection,
+    /// Failed to prepare a SQL statement for execution.
     PrepareStatement,
 }

01.workspace/heave/src/str/value.rs

@@ -1,11 +1,20 @@
 use crate::*;
 
+/// Represents the value of an entity's attribute.
+///
+/// This enum can hold different data types, allowing for flexible and
+/// semi-structured data storage.
 #[derive(Debug, PartialEq, PartialOrd, Clone)]
 pub enum Value {
+    /// A boolean value (`true` or `false`).
     Bool(bool),
+    /// A floating-point number (`f64`).
     Real(f64),
+    /// A signed 64-bit integer.
     SignedInt(i64),
+    /// A UTF-8 encoded string.
     Text(String),
+    /// An unsigned 64-bit integer.
     UnsignedInt(u64),
 }