Add comment.

src/lib/collection.html

@@ -105,6 +105,14 @@
       return items;
     },
 
+    // Accepts an array of standard splice records (index, addedCount, removed
+    // array), and performs two key actions:
+    // 1. Applies the splice to the collection: adds newly added items to the
+    //    store which generates a unique key for it, and removes removed items
+    //    (and their key) from the store
+    // 2. Generates a "keySplices" record (in contrast to the input
+    //    "indexSplices"), which contains an array of added and removed keys
+    //    corresponding to the added/removed items
     _applySplices: function(splices) {
       // Dedupe added and removed keys to a final added/removed map
       var keyMap = {}, key, i;
@@ -119,6 +127,9 @@
           key = this.getKey(item);
           key = (key === undefined) ? this.add(item) : key;
           keyMap[key] = keyMap[key] ? null : 1;
+          // Add an "addedKeys" array to indexSplices to capture keys associated
+          // with added items, since references to added items can be lost by
+          // further changes to the array by the time the splice is consumed
           s.addedKeys.push(key);
         }
       }, this);