more explanation

Author: anderoonies

lib/document.js

@@ -109,7 +109,7 @@ class Document {
   /*
   Public: Modify the Document's text.
 
-  The modification can be a deletion, insertion, or both.
+  The modification can be a deletion, insertion, or both (an overwrite).
   If `end` is after `start` in the document, the operation is a deletion.
   If `text` is passed, the operation is an insertion.
 
@@ -176,6 +176,7 @@ class Document {
   * `layerUpdatesById` {Object} of shape:
     * {Number} Marker layer ID
       * {Numer} Marker ID
+        * {Marker}
 
   Returns an {Array} of the marker update operation.
   */
@@ -236,7 +237,9 @@ class Document {
   }
 
   /*
-  Public: Undoes one or more operations.
+  Public: Undoes the latest Transaction on the undo stack.
+
+  If there's a barrier before the latest Transaction, nothing happens.
 
   Returns null or {Object} of shape:
     * `markers` {Object} of shape:
@@ -279,7 +282,7 @@ class Document {
   }
 
   /*
-  Public: Redoes one or more operations.
+  Public: Redoes the latest Transaction on the redo stack.
 
   Returns null or {Object} of shape:
     * `markers` {Object} of shape:
@@ -332,9 +335,13 @@ class Document {
   }
 
   /*
-  Public: Sets the interval for grouping transactions.
+  Public: Sets the interval for grouping Transactions.
+
+  If the updates grouping interval would contain the two latest transactions,
+  they are grouped.
 
   * `groupingInterval` {Number} of milliseconds
+
   */
   applyGroupingInterval (groupingInterval) {
     const topEntry = this.undoStack[this.undoStack.length - 1]
@@ -419,6 +426,9 @@ class Document {
   /*
   Public: Reverts the document to a checkpoint in the undo stack.
 
+  If a barrier exists in the undo stack before the checkpoint matching
+  `checkpointId`, the reversion fails.
+
   * `checkpointId` {Number}
   * `options` {Object} of shape:
     * `deleteCheckpoint` {Bool}
@@ -791,7 +801,6 @@ class Document {
 
   Returns {Object} of shape:
   * `markerUpdates` {Object} of shape:
-  // TODO confirm site ID here
     * {Number} Site ID
       * {Number} Marker layer ID
         * {Number} Marker ID

lib/serialization.js

@@ -1,5 +1,12 @@
 const {Operation} = require('./teletype-crdt_pb')
 
+/*
+Public: Serializes an operation.
+
+* `op` operation {Object}, either a splice, undo, or marker update.
+
+Returns a serialize message {Object}
+*/
 function serializeOperation (op) {
   const operationMessage = new Operation()
   switch (op.type) {
@@ -118,6 +125,13 @@ function serializePoint ({row, column}) {
   return pointMessage
 }
 
+/*
+Public: Serializes an operation.
+
+* `operationMessage` operation message {Object}
+
+Returns an operation {Object}
+*/
 function deserializeOperation (operationMessage) {
   if (operationMessage.hasSplice()) {
     return deserializeSplice(operationMessage.getSplice())