From e9b136341bea14f293aa21cde867b3b80fff75dc Mon Sep 17 00:00:00 2001
From: davidemazzocchi <davide.mazzocchi@gmail.com>
Date: Tue, 11 Nov 2025 16:31:26 +0100
Subject: [PATCH] doc: add documentation for catalog.for_each and
 catalog.for_each_mut

---
 01.workspace/heave/src/imp/catalog_for_each.rs  | 17 +++++++++++++++++
 .../heave/src/imp/catalog_for_each_mut.rs       | 17 +++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/01.workspace/heave/src/imp/catalog_for_each.rs b/01.workspace/heave/src/imp/catalog_for_each.rs
index 298b790..032fe6d 100644
--- a/01.workspace/heave/src/imp/catalog_for_each.rs
+++ b/01.workspace/heave/src/imp/catalog_for_each.rs
@@ -1,6 +1,23 @@
 use crate::*;
 
 impl Catalog {
+    /// Iterates over each item in the catalog that can be converted into type `T` and applies a predicate function.
+    ///
+    /// This method allows read-only iteration over entities. The predicate receives an immutable reference
+    /// to the item.
+    ///
+    /// # Type Parameters
+    ///
+    /// * `T`: The target type that entities should be converted into. Must implement `EAV`.
+    /// * `F`: The type of the predicate function.
+    ///
+    /// # Arguments
+    ///
+    /// * `predicate`: A mutable closure that takes an immutable reference to an item of type `T`.
+    ///
+    /// # Returns
+    ///
+    /// A `Result` indicating success (`Ok(())`) or failure (`Err(FailedTo)`).
     pub fn for_each<T, F>(&self, mut predicate: F) -> Result<(), FailedTo>
     where
         T: EAV,
diff --git a/01.workspace/heave/src/imp/catalog_for_each_mut.rs b/01.workspace/heave/src/imp/catalog_for_each_mut.rs
index 0eaa000..205acef 100644
--- a/01.workspace/heave/src/imp/catalog_for_each_mut.rs
+++ b/01.workspace/heave/src/imp/catalog_for_each_mut.rs
@@ -1,6 +1,23 @@
 use crate::*;
 
 impl Catalog {
+    /// Iterates over each item in the catalog that can be converted into type `T` and applies a mutable predicate function.
+    ///
+    /// This method allows mutable iteration over entities. If the item is modified by the predicate,
+    /// its state in the catalog will be marked as `EntityState::Updated`.
+    ///
+    /// # Type Parameters
+    ///
+    /// * `T`: The target type that entities should be converted into. Must implement `EAV`.
+    /// * `F`: The type of the predicate function.
+    ///
+    /// # Arguments
+    ///
+    /// * `predicate`: A mutable closure that takes a mutable reference to an item of type `T` and returns a `Result<(), Box<dyn error::Error>>`. If the predicate returns an `Err`, it will be mapped to `FailedTo::ExecutePredicate`.
+    ///
+    /// # Returns
+    ///
+    /// A `Result` indicating success (`Ok(())`) or failure (`Err(FailedTo)`).
     pub fn for_each_mut<T, F>(&self, mut predicate: F) -> Result<(), FailedTo>
     where
         T: EAV,