From a5396a9142c3dad2a63d12789fc3bc82f6235d3a Mon Sep 17 00:00:00 2001
From: Micha Reiser <micha@reiser.io>
Date: Sat, 21 Sep 2024 16:34:42 +0200
Subject: [PATCH] Add comments

---
 src/function/diff_outputs.rs | 6 ++++++
 src/zalsa_local.rs           | 7 ++++++-
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/src/function/diff_outputs.rs b/src/function/diff_outputs.rs
index eb3afbe4..6c7b9b90 100644
--- a/src/function/diff_outputs.rs
+++ b/src/function/diff_outputs.rs
@@ -1,4 +1,5 @@
 use super::{memo::Memo, Configuration, IngredientImpl};
+use crate::tracked_struct::KeyStruct;
 use crate::{
     hash::FxHashSet, key::DependencyIndex, zalsa_local::QueryRevisions, AsDynDatabase as _,
     DatabaseKeyIndex, Event, EventKind,
@@ -10,6 +11,9 @@ where
 {
     /// Compute the old and new outputs and invoke the `clear_stale_output` callback
     /// for each output that was generated before but is not generated now.
+    ///
+    /// This function takes a `&mut` reference to `revisions` to remove outputs
+    /// that no longer exist in this revision from [`QueryRevisions::tracked_struct_ids`].
     pub(super) fn diff_outputs(
         &self,
         db: &C::DbView,
@@ -27,6 +31,8 @@ where
         }
 
         if !old_outputs.is_empty() {
+            // Remove the outputs that are no longer present in the current revision
+            // to prevent that the next revision is seeded with a id mapping that no longer exists.
             revisions.tracked_struct_ids.retain(|_k, value| {
                 !old_outputs.contains(&DependencyIndex {
                     ingredient_index: value.ingredient_index,
diff --git a/src/zalsa_local.rs b/src/zalsa_local.rs
index 877b47b7..53c063db 100644
--- a/src/zalsa_local.rs
+++ b/src/zalsa_local.rs
@@ -353,7 +353,12 @@ pub(crate) struct QueryRevisions {
 
     /// The ids of tracked structs created by this query.
     /// This is used to seed the next round if the query is
-    /// re-executed.
+    /// re-executed. This ensures that tracked structs
+    /// have the same id across revisions.
+    ///
+    /// [`diff_outputs`] removes tracked structs that were created
+    /// in a previous revision but no longer exist
+    /// in the new revision.
     pub(super) tracked_struct_ids: FxHashMap<KeyStruct, DatabaseKeyIndex>,
 }