Add a short comment on every method in the new editor code.

lib/rga.js

@@ -309,6 +309,7 @@ RGA.AceEditorRGA = function AceEditorRGA(id, editor, history, queue) {
 
 RGA.AceEditorRGA.prototype = Object.create(RGA.prototype);
 Object.assign(RGA.AceEditorRGA.prototype, {
+  // Return the {row, column} coordinates of the character with timestamp t.
   getRowColumnBefore: function (t) {
     if (t === this.left.timestamp)
       throw new Error("no position before the left edge of the document");
@@ -329,6 +330,8 @@ Object.assign(RGA.AceEditorRGA.prototype, {
     return {row: r, column: c};
   },
 
+  // Return the coordinates of a hypothetical new character, if you inserted it
+  // with timestamp `wt`, after the character with timestamp `t`.
   getRowColumnAfter: function (t, wt) {
     var target = this._index.get(t);
     if (target === undefined)
@@ -359,19 +362,20 @@ Object.assign(RGA.AceEditorRGA.prototype, {
     return {row: r, column: c};
   },
 
+  // Throw if the this._lastText and the RGA don't have the same value.
   _assertInSync: function () {
     var erText = this.text();
     if (this._lastText != erText) {
       infodump.lastText = this._lastText;
       infodump.rgaText = erText;
-      console.error(this.id, "lastText and rga are out of sync", infodump);
+      console.error(this.id, "lastText and RGA are out of sync", infodump);
       throw new Error("editor and RGA data structure got out of sync");
     }
   },
 
-  // Convenience method to apply a patch. The structure of `delta` is the same
-  // as a Quill delta, just because it was a JSON patch format I knew about --
-  // RGA doesn't actually use any Quill code.
+  // Apply a patch to the RGA only, without touching the editor. The structure
+  // of `delta` is the same as a Quill delta, just because it was a JSON patch
+  // format I knew about -- we don't actually use any Quill code.
   _applyDelta: function (delta) {
     var source = this.downstream;
     var lastNode = this.left, node = lastNode.next;
@@ -414,6 +418,8 @@ Object.assign(RGA.AceEditorRGA.prototype, {
     }
   },
 
+  // Compare current editor value against the last known editor value. Any
+  // differences are recent user edits; apply them to the RGA.
   _takeUserEdits: function () {
     var currentText = this.editor.getValue();
     //this._log("_takeUserEdits: <" + currentText + "> <" + this._lastText + ">");
@@ -430,16 +436,20 @@ Object.assign(RGA.AceEditorRGA.prototype, {
     }
   },
 
+  // Unsubscribe from the editor's change notifications, call action(), then
+  // re-subscribe.
   _withEditorCallbacksDisabled: function(action) {
     this.editor.getSession().off("change", this._changeCallback);
-    action();
-    this.editor.getSession().on("change", this._changeCallback);
+    try {
+      action();
+    } finally {
+      this.editor.getSession().on("change", this._changeCallback);
+    }
   },
 
   // Apply an RGA op to the Ace editor.
   _applyOpToEditor: function (op) {
-    var editor = this.editor;
-    var session = editor.getSession();
+    var session = this.editor.getSession();
     switch (op.type) {
     case "addRight":
       if (this._index.has(op.w.timestamp)) {
@@ -477,6 +487,7 @@ Object.assign(RGA.AceEditorRGA.prototype, {
     }
   },
 
+  // Receive an op from a peer RGA or (equivalently) a socket.
   _customDownstream: function (source, op) {
     // Always check for new user edits *before* accepting ops from the internet.
     // That way, _takeUserEdits() knows that all differences between
@@ -488,7 +499,7 @@ Object.assign(RGA.AceEditorRGA.prototype, {
     // already been inserted/deleted, we have to call that first,
     // before modifying the RGA.
     this._applyOpToEditor(op);  // first update the editor
-    this._downstream(source, op);  // then update the RGA
+    this._downstream(source, op);  // then call base-class method to update the RGA
     this._lastText = this.editor.getValue();
 
     this._assertInSync({op: op});