add more documentation

Author: webzwo0i

src/static/js/Changeset.js

@@ -673,6 +673,13 @@ exports.textLinesMutator = function (lines) {
     inSplice = false;
   }
 
+  /**
+   * Indicates if curLine is already in the splice. This is necessary because the last element
+   * in curSplice is curLine when this line is currently worked on (e.g. when skipping are inserting)
+   *
+   * TODO(doc) why aren't removals considered?
+   * @returns {Boolean} true if curLine is in splice
+   */
   function isCurLineInSplice() {
     return (curLine - curSplice[0] < (curSplice.length - 2));
   }
@@ -681,20 +688,32 @@ exports.textLinesMutator = function (lines) {
     print(typ + ": " + curSplice.toSource() + " / " + curLine + "," + curCol + " / " + lines_toSource());
   }
 
+  /**
+   * Incorporates current line into the splice
+   * and marks its old position to be deleted.
+   *
+   * @returns {Number} the index of the added line in curSplice
+   */
   function putCurLineInSplice() {
     if (!isCurLineInSplice()) {
       curSplice.push(lines_get(curSplice[0] + curSplice[1]));
       curSplice[1]++;
     }
-    return 2 + curLine - curSplice[0];
+    return 2 + curLine - curSplice[0]; // TODO should be the same as curSplice.length - 1
   }
 
+  /**
+   * It will skip some newlines by putting them into the splice.
+   *
+   * @param {Boolean} includeInSplice indicates if attributes are present
+   */
   function skipLines(L, includeInSplice) {
     if (L) {
       if (includeInSplice) {
         if (!inSplice) {
           enterSplice();
         }
+        // TODO(doc) should this count the number of characters that are skipped to check?
         for (var i = 0; i < L; i++) {
           curCol = 0;
           putCurLineInSplice();
@@ -703,6 +722,7 @@ exports.textLinesMutator = function (lines) {
       } else {
         if (inSplice) {
           if (L > 1) {
+            // TODO(doc) figure out why single lines are incorporated into splice instead of ignored
             leaveSplice();
           } else {
             putCurLineInSplice();
@@ -721,6 +741,13 @@ exports.textLinesMutator = function (lines) {
     //debugPrint("skip");
   }
 
+  /**
+   * Skip some characters. Can contain newlines.
+   *
+   * @param {Number} N number of characters to skip
+   * @param {Number} L number of newlines to skip
+   * @param {Boolean} includeInSplice indicates if attributes are present 
+   */
   function skip(N, L, includeInSplice) {
     if (N) {
       if (L) {
@@ -730,6 +757,8 @@ exports.textLinesMutator = function (lines) {
           enterSplice();
         }
         if (inSplice) {
+          // although the line is put into splice curLine is not increased, because
+          // only some chars are skipped, not the whole line
           putCurLineInSplice();
         }
         curCol += N;
@@ -738,13 +767,24 @@ exports.textLinesMutator = function (lines) {
     }
   }
 
+  /**
+   * Remove whole lines from lines array
+   *
+   * @param {Number} L number of lines to be removed
+   */
   function removeLines(L) {
     var removed = '';
     if (L) {
       if (!inSplice) {
         enterSplice();
       }
 
+      /**
+       * Gets a string of joined lines after the end of the splice
+       *
+       * @param k {Number} number of lines
+       * @returns {String} joined lines
+       */
       function nextKLinesText(k) {
         var m = curSplice[0] + curSplice[1];
         return lines_slice(m, m + k).join('');
@@ -774,6 +814,12 @@ exports.textLinesMutator = function (lines) {
     return removed;
   }
 
+  /**
+   * Remove text from lines array
+   *
+   * @param N {Number} characters to delete
+   * @param L {Number} lines to delete
+   */
   function remove(N, L) {
     var removed = '';
     if (N) {
@@ -783,6 +829,8 @@ exports.textLinesMutator = function (lines) {
         if (!inSplice) {
           enterSplice();
         }
+        // although the line is put into splice, curLine is not increased, because
+        // only some chars are removed not the whole line
         var sline = putCurLineInSplice();
         removed = curSplice[sline].substring(curCol, curCol + N);
         curSplice[sline] = curSplice[sline].substring(0, curCol) + curSplice[sline].substring(curCol + N);
@@ -792,6 +840,12 @@ exports.textLinesMutator = function (lines) {
     return removed;
   }
 
+  /**
+   * Inserts text into lines array.
+   *
+   * @param text {String} the text to insert
+   * @param L {Number} number of newlines in text
+   */
   function insert(text, L) {
     if (text) {
       if (!inSplice) {
@@ -831,6 +885,12 @@ exports.textLinesMutator = function (lines) {
     }
   }
 
+  /**
+   * Checks if curLine (the line we are in when curSplice is applied) is the last line
+   * in lines.
+   *
+   * @return {Boolean} indicates if there are lines left
+   */
   function hasMore() {
     //print(lines.length+" / "+inSplice+" / "+(curSplice.length - 2)+" / "+curSplice[1]);
     var docLines = lines_length();
@@ -840,6 +900,9 @@ exports.textLinesMutator = function (lines) {
     return curLine < docLines;
   }
 
+  /**
+   * Closes the splice
+   */
   function close() {
     if (inSplice) {
       leaveSplice();