editor: Improve documentation comments

src/static/js/AttributeManager.js

@@ -115,13 +115,13 @@ AttributeManager.prototype = _(AttributeManager.prototype).extend({
     return [startCol, endCol];
   },
 
-  /*
+  /**
-    Sets attributes on a range, by line
+   * Sets attributes on a range, by line
-    @param row the row where range is
+   * @param row the row where range is
-    @param startCol column where range starts
+   * @param startCol column where range starts
-    @param endCol column where range ends
+   * @param endCol column where range ends (one past the last selected column)
-    @param attribs: an array of attributes
+   * @param attribs an array of attributes
-  */
+   */
   _setAttributesOnRangeByLine(row, startCol, endCol, attribs) {
     const builder = Changeset.builder(this.rep.lines.totalWidth());
     ChangesetUtils.buildKeepToStartOfRange(this.rep, builder, [row, startCol]);

src/static/js/ace2_inner.js

@@ -86,14 +86,24 @@ function Ace2Inner(editorInfo, cssManagers) {
   let outsideKeyPress = (e) => true;
   let outsideNotifyDirty = noop;
 
-  // selFocusAtStart -- determines whether the selection extends "backwards", so that the focus
+  // Document representation.
-  // point (controlled with the arrow keys) is at the beginning; not supported in IE, though
-  // native IE selections have that behavior (which we try not to interfere with).
-  // Must be false if selection is collapsed!
   const rep = {
+    // Each entry in this skip list is an object created by createDomLineEntry(). The object
+    // represents a line (paragraph) of content.
     lines: new SkipList(),
+    // Points at the start of the selection. Represented as [zeroBasedLineNumber,
+    // zeroBasedColumnNumber].
+    // TODO: If the selection starts at the beginning of a line, I think this could be either
+    // [lineNumber, 0] or [previousLineNumber, previousLineLength]. Need to confirm.
     selStart: null,
+    // Points at the character just past the last selected character. Same representation as
+    // selStart.
+    // TODO: If the last selected character is the last character of a line, I think this could be
+    // either [lineNumber, lineLength] or [lineNumber+1, 0]. Need to confirm.
     selEnd: null,
+    // Whether the selection extends "backwards", so that the focus point (controlled with the arrow
+    // keys) is at the beginning. This is not supported in IE, though native IE selections have that
+    // behavior (which we try not to interfere with). Must be false if selection is collapsed!
     selFocusAtStart: false,
     alltext: '',
     alines: [],
@@ -646,9 +656,11 @@ function Ace2Inner(editorInfo, cssManagers) {
     }
   };
 
-  // This methed exposes a setter for some ace properties
+  /**
-  // @param key the name of the parameter
+   * This methed exposes a setter for some ace properties
-  // @param value the value to set to
+   * @param key the name of the parameter
+   * @param value the value to set to
+   */
   editorInfo.ace_setProperty = (key, value) => {
     // These properties are exposed
     const setters = {
@@ -1301,8 +1313,6 @@ function Ace2Inner(editorInfo, cssManagers) {
   editorInfo.ace_isCaret = isCaret;
 
   // prereq: isCaret()
-
-
   const caretLine = () => rep.selStart[0];
 
   editorInfo.ace_caretLine = caretLine;
@@ -1542,9 +1552,9 @@ function Ace2Inner(editorInfo, cssManagers) {
     }
   };
 
-  /*
+  /**
-    Converts the position of a char (index in String) into a [row, col] tuple
+   * Converts the position of a char (index in String) into a [row, col] tuple
-  */
+   */
   const lineAndColumnFromChar = (x) => {
     const lineEntry = rep.lines.atOffset(x);
     const lineStart = rep.lines.offsetOfEntry(lineEntry);

src/static/js/skiplist.js

@@ -24,6 +24,10 @@
 
 const _ = require('./underscore');
 
+/**
+ * The skip-list contains "entries", JavaScript objects that each must have a unique "key"
+ * property that is a string.
+ */
 function SkipList() {
   // if there are N elements in the skiplist, "start" is element -1 and "end" is element N
   const start = {
@@ -47,13 +51,12 @@ function SkipList() {
   const keyToNodeMap = {};
   start.downPtrs[0] = end;
   end.upPtrs[0] = start;
+
   // a "point" object at location x allows modifications immediately after the first
   // x elements of the skiplist, such as multiple inserts or deletes.
   // After an insert or delete using point P, the point is still valid and points
   // to the same index in the skiplist.  Other operations with other points invalidate
   // this point.
-
-
   const _getPoint = (targetLoc) => {
     const numLevels = start.levels;
     let lvl = numLevels - 1;
@@ -225,8 +228,6 @@ function SkipList() {
   // Returns index of first entry such that entryFunc(entry) is truthy,
   // or length() if no such entry.  Assumes all falsy entries come before
   // all truthy entries.
-
-
   const _search = (entryFunc) => {
     let low = start;
     let lvl = start.levels - 1;
@@ -250,10 +251,6 @@ function SkipList() {
     return lowIndex + 1;
   };
 
-  /*
-The skip-list contains "entries", JavaScript objects that each must have a unique "key" property
-that is a string.
-  */
   const self = this;
   _.extend(this, {
     length: () => numNodes,