Apply suggestions from code review

src/ingredient.rs

@@ -28,9 +28,23 @@ pub trait Jar: Any {
     fn salsa_struct_type_id(&self) -> Option<TypeId>;
 }
 
+/// Methods on the Salsa database available to jars while they are creating their ingredients.
 pub trait JarAux {
+    /// Return index of first ingredient from `jar` (based on the dynamic type of `jar`).
+    /// Returns `None` if the jar has not yet been added. 
+    /// Used by tracked functions to lookup the ingredient index for the salsa struct they take as argument.
     fn lookup_jar_by_type(&self, jar: &dyn Jar) -> Option<IngredientIndex>;
 
+    /// Returns the memo ingredient index that should be used to attach data from the given tracked function
+    /// to the given salsa struct (which the fn accepts as argument).
+    ///
+    /// The memo ingredient indices for a given function must be distinct from the memo indices
+    /// of all other functions that take the same salsa struct.
+    ///
+    /// # Parameters
+    ///
+    /// * `struct_ingredient_index`, the index of the salsa struct the memo will be attached to
+    /// * `ingredient_index`, the index of the tracked function whose data is stored in the memo
     fn next_memo_ingredient_index(
         &self,
         struct_ingredient_index: IngredientIndex,

src/zalsa.rs

@@ -189,6 +189,12 @@ impl Zalsa {
             let jar_type_id = jar.type_id();
             let mut jar_map = self.jar_map.lock();
             let mut should_create = false;
+            // First record the index we will use into the map and then go and create the ingredients.
+            // Those ingredients may invoke methods on the `JarAux` trait that read from this map
+            // to lookup ingredient indices for already created jars.
+            //
+            // Note that we still hold the lock above so only one jar is being created at a time and hence
+            // ingredient indices cannot overlap.
             let index = *jar_map.entry(jar_type_id).or_insert_with(|| {
                 should_create = true;
                 IngredientIndex::from(self.ingredients_vec.len())