add more documentation

src/static/js/Changeset.js

@@ -640,26 +640,45 @@ exports.textLinesMutator = (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
+   */
   const isCurLineInSplice = () => (curLine - curSplice[0] < (curSplice.length - 2));
 
   const debugPrint = (typ) => { /* eslint-disable-line no-unused-vars */
     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
+   */
   const 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
+   */
   const 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 (let i = 0; i < L; i++) {
           curCol = 0;
           putCurLineInSplice();
@@ -668,6 +687,7 @@ exports.textLinesMutator = (lines) => {
       } else {
         if (inSplice) {
           if (L > 1) {
+            // TODO(doc) figure out why single lines are incorporated into splice instead of ignored
             leaveSplice();
           } else {
             putCurLineInSplice();
@@ -680,6 +700,13 @@ exports.textLinesMutator = (lines) => {
     }
   };
 
+  /**
+   * 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
+   */
   const skip = (N, L, includeInSplice) => {
     if (N) {
       if (L) {
@@ -689,20 +716,33 @@ exports.textLinesMutator = (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;
       }
     }
   };
 
+  /**
+   * Remove whole lines from lines array
+   *
+   * @param {Number} L number of lines to be removed
+   */
   const removeLines = (L) => {
     let 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
+       */
       const nextKLinesText = (k) => {
         const m = curSplice[0] + curSplice[1];
         return lines_slice(m, m + k).join('');
@@ -730,6 +770,12 @@ exports.textLinesMutator = (lines) => {
     return removed;
   };
 
+  /**
+   * Remove text from lines array
+   *
+   * @param N {Number} characters to delete
+   * @param L {Number} lines to delete
+   */
   const remove = (N, L) => {
     let removed = '';
     if (N) {
@@ -739,6 +785,8 @@ exports.textLinesMutator = (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
         const sline = putCurLineInSplice();
         removed = curSplice[sline].substring(curCol, curCol + N);
         curSplice[sline] = curSplice[sline].substring(0, curCol) +
@@ -748,6 +796,12 @@ exports.textLinesMutator = (lines) => {
     return removed;
   };
 
+  /**
+   * Inserts text into lines array.
+   *
+   * @param text {String} the text to insert
+   * @param L {Number} number of newlines in text
+   */
   const insert = (text, L) => {
     if (text) {
       if (!inSplice) {
@@ -782,6 +836,12 @@ exports.textLinesMutator = (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
+   */
   const hasMore = () => {
     let docLines = lines_length();
     if (inSplice) {
@@ -790,6 +850,9 @@ exports.textLinesMutator = (lines) => {
     return curLine < docLines;
   };
 
+  /**
+   * Closes the splice
+   */
   const close = () => {
     if (inSplice) {
       leaveSplice();