From 37a33042d24648185d90a48593d981fb6024365c Mon Sep 17 00:00:00 2001
From: Richard Hansen <rhansen@rhansen.org>
Date: Sat, 2 Oct 2021 02:02:04 -0400
Subject: [PATCH] ace2_inner: Improve rep documentation

---
 src/static/js/ace2_inner.js | 49 ++++++++++++++++++++++++++-----------
 1 file changed, 35 insertions(+), 14 deletions(-)

diff --git a/src/static/js/ace2_inner.js b/src/static/js/ace2_inner.js
index 03dd925bb..4b1d66317 100644
--- a/src/static/js/ace2_inner.js
+++ b/src/static/js/ace2_inner.js
@@ -81,24 +81,45 @@ function Ace2Inner(editorInfo, cssManagers) {
   let outsideKeyPress = (e) => true;
   let outsideNotifyDirty = noop;
 
-  // Document representation.
+  /**
+   * Document representation.
+   */
   const rep = {
-    // Each entry in this skip list is an object created by createDomLineEntry(). The object
-    // represents a line (paragraph) of content.
+    /**
+     * The contents of the document. Each entry in this skip list is an object representing a
+     * line (actually paragraph) of text. The line objects are created by createDomLineEntry().
+     */
     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.
+    /**
+     * Start of the selection. Represented as an array of two non-negative numbers that point to the
+     * first character of the selection: [zeroBasedLineNumber, zeroBasedColumnNumber]. Notes:
+     *   - There is an implicit newline character (not actually stored) at the end of every line.
+     *     Because of this, a selection that starts at the end of a line (column number equals the
+     *     number of characters in the line, not including the implicit newline) is not equivalent
+     *     to a selection that starts at the beginning of the next line. The same goes for the
+     *     selection end.
+     *   - If there are N lines, [N, 0] is valid for the start of the selection. [N, 0] indicates
+     *     that the selection starts just after the implicit newline at the end of the document's
+     *     last line (if the document has any lines). The same goes for the end of the selection.
+     *   - If a line starts with a line marker, a selection that starts at the beginning of the line
+     *     may start either immediately before (column = 0) or immediately after (column = 1) the
+     *     line marker, and the two are considered to be semantically equivalent. For safety, all
+     *     code should be written to accept either but only produce selections that start after the
+     *     line marker (the column number should be 1, not 0, when there is a line marker). The same
+     *     goes for the end of the selection.
+     */
     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.
+    /**
+     * End of the selection. Represented as an array of two non-negative numbers that point to the
+     * character just after the end of the selection: [zeroBasedLineNumber, zeroBasedColumnNumber].
+     * See the above notes for selStart.
+     */
     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!
+    /**
+     * 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: [],