Add clarifying comments to 'getRemovalRange'

Summary:
I found some of this code confusing and added comments. Will probably
add more comments while looking at this part of the code.

For now pushing this before I lose track of things. Not in any hurry to merge it.
Closes facebookarchive#1103

Reviewed By: mitermayer

Differential Revision: D7137918

Pulled By: mitermayer

fbshipit-source-id: 350786c4817e122efbce146f6e6ccc26ed12ae0f

src/model/transaction/removeEntitiesAtEdges.js

@@ -65,18 +65,36 @@ function removeEntitiesAtEdges(
   });
 }
 
+/**
+ * Given a list of characters and an offset that is in the middle of an entity,
+ * returns the start and end of the entity that is overlapping the offset.
+ * Note: This method requires that the offset be in an entity range.
+ */
 function getRemovalRange(
   characters: List<CharacterMetadata>,
-  key: ?string,
+  entityKey: ?string,
   offset: number,
-): Object {
+): {
+  start: number,
+  end: number,
+} {
   var removalRange;
+
+  // Iterates through a list looking for ranges of matching items
+  // based on the 'isEqual' callback.
+  // Then instead of returning the result, call the 'found' callback
+  // with each range.
+  // Then filters those ranges based on the 'filter' callback
+  //
+  // Here we use it to find ranges of characters with the same entity key.
   findRangesImmutable(
-    characters,
-    (a, b) => a.getEntity() === b.getEntity(),
-    element => element.getEntity() === key,
-    (start, end) => {
+    characters, // the list to iterate through
+    (a, b) => a.getEntity() === b.getEntity(), // 'isEqual' callback
+    element => element.getEntity() === entityKey, // 'filter' callback
+    (start: number, end: number) => {
+      // 'found' callback
       if (start <= offset && end >= offset) {
+        // this entity overlaps the offset index
         removalRange = {start, end};
       }
     },