first pass

Author: anderoonies

lib/document.js

@@ -79,6 +79,11 @@ class Document {
     return replica
   }
 
+  /*
+  Public: Get operations integrated in the document.
+
+  Returns an {Array} of operations and marker updates.
+  */
   getOperations () {
     const markerOperations = []
     this.markerLayersBySiteId.forEach((layersById, siteId) => {
@@ -101,6 +106,20 @@ class Document {
     return this.operations.concat(markerOperations)
   }
 
+  /*
+  Public: Modify the Document's text.
+
+  The modification can be a deletion, insertion, or both.
+  If `end` is after `start` in the document, the operation is a deletion.
+  If `text` is passed, the operation is an insertion.
+
+  * `start` {Point}
+  * `end` {Point}
+  * `text` {String}
+  * `options` unused TODO
+
+  Returns an {Array} containing the integrated operation.
+  */
   setTextInRange (start, end, text, options) {
     const spliceId = {site: this.siteId, seq: this.nextSequenceNumber}
     const operation = {type: 'splice', spliceId}
@@ -120,6 +139,15 @@ class Document {
     return [operation]
   }
 
+  /*
+  Public: Get markers present in the Document.
+
+  Returns an {Object} of shape:
+    * {Number} Site ID
+      * {Number} Marker layer ID
+        * {Number} Marker ID
+          * {Marker}
+  */
   getMarkers () {
     const result = {}
     this.markerLayersBySiteId.forEach((layersById, siteId) => {
@@ -139,6 +167,18 @@ class Document {
     return result
   }
 
+  /*
+  Public: Updates markers in the Document.
+
+  If a Marker exists with the specified ID, its value is updated.
+  If no Marker exists with the specified ID, one is created.
+
+  * `layerUpdatesById` {Object} of shape:
+    * {Number} Marker layer ID
+      * {Numer} Marker ID
+
+  Returns an {Array} of the marker update operation.
+  */
   updateMarkers (layerUpdatesById) {
     const operation = {
       type: 'markers-update',
@@ -195,6 +235,23 @@ class Document {
     return [operation]
   }
 
+  /*
+  Public: Undoes one or more operations.
+
+  Returns null or {Object} of shape:
+    * `markers` {Object} of shape:
+      * {Number} Marker layer ID
+        * {Number} Marker ID
+          * {Marker}
+    * `textUpdates` {Array} of {Object}s of shape:
+      * `oldStart` {Point}
+      * `oldEnd` {Point}
+      * `oldText` {String}
+      * `newStart` {Point}
+      * `newEnd` {Point}
+      * `newText` {String}
+    * `operations` {Array} of operations
+  */
   undo () {
     let spliceIndex = null
     let operationsToUndo = []
@@ -221,6 +278,23 @@ class Document {
     }
   }
 
+  /*
+  Public: Redoes one or more operations.
+
+  Returns null or {Object} of shape:
+    * `markers` {Object} of shape:
+      * {Number} Marker layer ID
+        * {Number} Marker ID
+          * {Marker}
+    * `textUpdates` {Array} of {Object}s of shape:
+      * `oldStart: {Point}
+      * `oldEnd` {Point}
+      * `oldText` {String}
+      * `newStart` {Point}
+      * `newEnd` {Point}
+      * `newText` {String}
+    * `operations` {Array} of operations
+  */
   redo () {
     let spliceIndex = null
     let operationsToRedo = []
@@ -257,6 +331,11 @@ class Document {
     this.redoStack.length = 0
   }
 
+  /*
+  Public: Sets the interval for grouping transactions.
+
+  * `groupingInterval` {Number} of milliseconds
+  */
   applyGroupingInterval (groupingInterval) {
     const topEntry = this.undoStack[this.undoStack.length - 1]
     const previousEntry = this.undoStack[this.undoStack.length - 2]
@@ -284,6 +363,15 @@ class Document {
     return Date.now()
   }
 
+  /*
+  Public: Creates a checkpoint in the undo stack.
+
+  * `options` {Object} of shape:
+    * `isBarrier` {Bool}
+    * `markers` {Array} of {Marker}s
+
+  Returns {Number}
+  */
   createCheckpoint (options) {
     const checkpoint = new Checkpoint(
       this.nextCheckpointId++,
@@ -328,6 +416,27 @@ class Document {
     }
   }
 
+  /*
+  Public: Reverts the document to a checkpoint in the undo stack.
+
+  * `checkpointId` {Number}
+  * `options` {Object} of shape:
+    * `deleteCheckpoint` {Bool}
+
+  Returns false if the revert couldn't be completed, else returns {Object} of shape:
+      * `markers` {Object} of shape:
+        * {Number} Marker layer ID
+          * {Number} Marker ID
+            * {Marker}
+      * `textUpdates` {Array} of {Object}s of shape:
+        * `oldStart` {Point}
+        * `oldEnd` {Point}
+        * `oldText` {String}
+        * `newStart` {Point}
+        * `newEnd` {Point}
+        * `newText` {String}
+      * `operations` {Array} of operations
+  */
   revertToCheckpoint (checkpointId, options) {
     if (this.isBarrierPresentBeforeCheckpoint(checkpointId)) return false
 
@@ -341,6 +450,19 @@ class Document {
     }
   }
 
+  /*
+  Public: Gets changes performed since a checkpoint.
+
+  * `checkpointId` {Number}
+
+  Returns false or {Array} of {Object}s of shape:
+    * `oldStart` {Point}
+    * `oldEnd` {Point}
+    * `oldText` {String}
+    * `newStart` {Point}
+    * `newEnd` {Point}
+    * `newText` {String}
+  */
   getChangesSinceCheckpoint (checkpointId) {
     const result = this.collectOperationsSinceCheckpoint(checkpointId, false, false)
     if (result) {
@@ -379,6 +501,11 @@ class Document {
     }
   }
 
+  /*
+  Public: Groups the last changes on the undo stack.
+
+  Returns true if a grouping was made, else false.
+  */
   groupLastChanges () {
     let lastTransaction
 
@@ -406,6 +533,63 @@ class Document {
     return false
   }
 
+  /*
+  Public: Get history entries from the undo and redo stacks.
+
+  * `maxEntries` {Number} of history entries to return
+
+  Returns {Object} of shape:
+    * `nextCheckpointId` {Number}
+    * `undoStack` {Array} of {Object}s, either of shape:
+      * `type` {String} 'transaction'
+      * `changes` {Array} of {Object}s of shape:
+          * `oldStart` {Point}
+          * `oldEnd` {Point}
+          * `oldText` {String}
+          * `newStart` {Point}
+          * `newEnd` {Point}
+          * `newText` {String}
+      * `markersBefore` {Object} of shape:
+        * {Number} Marker layer ID
+          * {Number} Marker ID
+            * {Marker}
+      * `markersAfter` {Object} of shape:
+        * {Number} Marker layer ID
+          * {Number} Marker ID
+            * {Marker}
+      or of shape
+      * `type` {String} 'checkpoint'
+      * `id` {Number}
+      * `markers` {Object} of shape:
+        * {Number} Marker layer ID
+          * {Number} Marker ID
+            * {Marker}
+    * `redoStack` {Array} of {Object}s, either of shape:
+      * `type` {String} 'transaction'
+      * `changes` {Array} of {Object}s of shape:
+          * `oldStart` {Point}
+          * `oldEnd` {Point}
+          * `oldText` {String}
+          * `newStart` {Point}
+          * `newEnd` {Point}
+          * `newText` {String}
+      * `markersBefore` {Object} of shape:
+        * {Number} Marker layer ID
+          * {Number} Marker ID
+            * {Marker}
+      * `markersAfter` {Object} of shape:
+        * {Number} Marker layer ID
+          * {Number} Marker ID
+            * {Marker}
+      or of shape
+      * `type` {String} 'checkpoint'
+      * `id` {Number}
+      * `markers` {Object} of shape:
+        * {Number} Marker layer ID
+          * {Number} Marker ID
+            * {Marker}
+
+  */
   getHistory (maxEntries) {
     const originalUndoCounts = new Map(this.undoCountsBySpliceId)
 
@@ -600,6 +784,26 @@ class Document {
     }
   }
 
+  /*
+  Public: Integrate operations locally.
+
+  * `operations` {Array} of operations.
+
+  Returns {Object} of shape:
+  * `markerUpdates` {Object} of shape:
+  // TODO confirm site ID here
+    * {Number} Site ID
+      * {Number} Marker layer ID
+        * {Number} Marker ID
+          * {Marker}
+  * `textUpdates` {Array} of {Object}s of shape:
+    * `oldStart` {Point}
+    * `oldEnd` {Point}
+    * `oldText` {String}
+    * `newStart` {Point}
+    * `newEnd` {Point}
+    * `newText` {String}
+  */
   integrateOperations (operations) {
     const integratedOperations = []
     let oldUndoCounts
@@ -1093,6 +1297,11 @@ class Document {
     }
   }
 
+  /*
+  Public: Get the text of the Document.
+
+  Returns {String}
+  */
   getText () {
     let text = ''
     const segments = this.documentTree.getSegments()