add some documentation for textLinesMutator

Author: webzwo0i

src/static/js/Changeset.js

@@ -550,22 +550,37 @@ exports.textLinesMutator = (lines) => {
   // is not actually a newline, but for the purposes of N and L values,
   // the caller should pretend it is, and for things to work right in that case, the input
   // to insert() should be a single line with no newlines.
+
+  // The splice holds information which lines are to be deleted or changed.
+  // curSplice[0] is an index into the lines array
+  // curSplice[1] is the number of lines that will be removed from lines
+  // the other elements represent mutated (changed by ops) lines or new lines (added by ops)
   const curSplice = [0, 0];
   let inSplice = false;
-  // position in document after curSplice is applied:
+
+  // position in lines after curSplice is applied:
   let curLine = 0;
   let curCol = 0;
   // invariant: if (inSplice) then (curLine is in curSplice[0] + curSplice.length - {2,3}) &&
   //            curLine >= curSplice[0]
   // invariant: if (inSplice && (curLine >= curSplice[0] + curSplice.length - 2)) then
   //            curCol == 0
 
+  /**
+   * Adds and/or removes entries at a specific offset in lines array
+   * It is called when leaving the splice
+   * @param {Array} s curSplice
+   */
   const lines_applySplice = (s) => {
     lines.splice.apply(lines, s);
   };
 
   const lines_toSource = () => lines.toSource();
 
+  /**
+   * Get a line from lines at given index
+   * @param {Number} idx an index
+   */
   const lines_get = (idx) => {
     if (lines.get) {
       return lines.get(idx);
@@ -575,6 +590,11 @@ exports.textLinesMutator = (lines) => {
   };
   // can be unimplemented if removeLines's return value not needed
 
+  /**
+   * Return a slice from lines array
+   * @param {Number} start the start index
+   * @param {Number} end the end index
+   */
   const lines_slice = (start, end) => {
     if (lines.slice) {
       return lines.slice(start, end);
@@ -583,6 +603,9 @@ exports.textLinesMutator = (lines) => {
     }
   };
 
+  /**
+   * Return the length of lines array
+   */
   const lines_length = () => {
     if ((typeof lines.length) === 'number') {
       return lines.length;
@@ -591,15 +614,25 @@ exports.textLinesMutator = (lines) => {
     }
   };
 
+  /**
+   * Starts a new splice.
+   */
   const enterSplice = () => {
     curSplice[0] = curLine;
     curSplice[1] = 0;
+    // TODO(doc) when is this the case?
+    //          check all enterSplice calls and changes to curCol
     if (curCol > 0) {
       putCurLineInSplice();
     }
     inSplice = true;
   };
 
+  /**
+   * Changes the lines array according to the values in curSplice
+   * and resets curSplice.
+   * This is called via close or TODO(doc)
+   */
   const leaveSplice = () => {
     lines_applySplice(curSplice);
     curSplice.length = 2;