gollum 2.4.4 → 2.4.5

data/lib/gollum/frontend/public/gollum/livepreview/js/ace/lib/ace/document_test.js

@@ -1,38 +1,30 @@
 /* ***** BEGIN LICENSE BLOCK *****
- * Version: MPL 1.1/GPL 2.0/LGPL 2.1
+ * Distributed under the BSD license:
  *
- * The contents of this file are subject to the Mozilla Public License Version
- * 1.1 (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- * http://www.mozilla.org/MPL/
- *
- * Software distributed under the License is distributed on an "AS IS" basis,
- * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
- * for the specific language governing rights and limitations under the
- * License.
- *
- * The Original Code is Ajax.org Code Editor (ACE).
- *
- * The Initial Developer of the Original Code is
- * Ajax.org B.V.
- * Portions created by the Initial Developer are Copyright (C) 2010
- * the Initial Developer. All Rights Reserved.
- *
- * Contributor(s):
- *      Fabian Jakobs <fabian AT ajax DOT org>
- *      Julian Viereck <julian.viereck@gmail.com>
- *
- * Alternatively, the contents of this file may be used under the terms of
- * either the GNU General Public License Version 2 or later (the "GPL"), or
- * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
- * in which case the provisions of the GPL or the LGPL are applicable instead
- * of those above. If you wish to allow use of your version of this file only
- * under the terms of either the GPL or the LGPL, and not to allow others to
- * use your version of this file under the terms of the MPL, indicate your
- * decision by deleting the provisions above and replace them with the notice
- * and other provisions required by the GPL or the LGPL. If you do not delete
- * the provisions above, a recipient may use your version of this file under
- * the terms of any one of the MPL, the GPL or the LGPL.
+ * Copyright (c) 2010, Ajax.org B.V.
+ * All rights reserved.
+ * 
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *     * Redistributions of source code must retain the above copyright
+ *       notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above copyright
+ *       notice, this list of conditions and the following disclaimer in the
+ *       documentation and/or other materials provided with the distribution.
+ *     * Neither the name of Ajax.org B.V. nor the
+ *       names of its contributors may be used to endorse or promote products
+ *       derived from this software without specific prior written permission.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL AJAX.ORG B.V. BE LIABLE FOR ANY
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  *
  * ***** END LICENSE BLOCK ***** */
 

data/lib/gollum/frontend/public/gollum/livepreview/js/ace/lib/ace/edit_session.js

@@ -1,40 +1,30 @@
-/* vim:ts=4:sts=4:sw=4:
- * ***** BEGIN LICENSE BLOCK *****
- * Version: MPL 1.1/GPL 2.0/LGPL 2.1
+/* ***** BEGIN LICENSE BLOCK *****
+ * Distributed under the BSD license:
  *
- * The contents of this file are subject to the Mozilla Public License Version
- * 1.1 (the "License"); you may not use this file except in compliance with
- * the License. You may obtain a copy of the License at
- * http://www.mozilla.org/MPL/
- *
- * Software distributed under the License is distributed on an "AS IS" basis,
- * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
- * for the specific language governing rights and limitations under the
- * License.
- *
- * The Original Code is Ajax.org Code Editor (ACE).
- *
- * The Initial Developer of the Original Code is
- * Ajax.org B.V.
- * Portions created by the Initial Developer are Copyright (C) 2010
- * the Initial Developer. All Rights Reserved.
- *
- * Contributor(s):
- *      Fabian Jakobs <fabian AT ajax DOT org>
- *      Mihai Sucan <mihai DOT sucan AT gmail DOT com>
- *      Julian Viereck <julian DOT viereck AT gmail DOT com>
- *
- * Alternatively, the contents of this file may be used under the terms of
- * either the GNU General Public License Version 2 or later (the "GPL"), or
- * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
- * in which case the provisions of the GPL or the LGPL are applicable instead
- * of those above. If you wish to allow use of your version of this file only
- * under the terms of either the GPL or the LGPL, and not to allow others to
- * use your version of this file under the terms of the MPL, indicate your
- * decision by deleting the provisions above and replace them with the notice
- * and other provisions required by the GPL or the LGPL. If you do not delete
- * the provisions above, a recipient may use your version of this file under
- * the terms of any one of the MPL, the GPL or the LGPL.
+ * Copyright (c) 2010, Ajax.org B.V.
+ * All rights reserved.
+ * 
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *     * Redistributions of source code must retain the above copyright
+ *       notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above copyright
+ *       notice, this list of conditions and the following disclaimer in the
+ *       documentation and/or other materials provided with the distribution.
+ *     * Neither the name of Ajax.org B.V. nor the
+ *       names of its contributors may be used to endorse or promote products
+ *       derived from this software without specific prior written permission.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL AJAX.ORG B.V. BE LIABLE FOR ANY
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  *
  * ***** END LICENSE BLOCK ***** */
 
@@ -54,32 +44,121 @@ var BackgroundTokenizer = require("./background_tokenizer").BackgroundTokenizer;
 var SearchHighlight = require("./search_highlight").SearchHighlight;
 
 /**
- * class EditSession
  *
- * Stores various states related to a [[Document `Document`]]. A single `EditSession` can be in charge of several `Document`s.
+ *
+ * Stores all the data about [[Editor `Editor`]] state providing easy way to change editors state.  
+ * 
+ * `EditSession` can be attached to only one [[Document `Document`]]. Same `Document` can be attached to several `EditSession`s.
+ * @class EditSession
+ **/
+
+// events 
+/**
+ *
+ * Emitted when the document changes.
+ * @event change
+ * @param {Object} e An object containing a `delta` of information about the change.
+ **/
+/**
+ * Emitted when the tab size changes, via [[EditSession.setTabSize]].
+ *
+ * @event changeTabSize
+ **/
+/**
+ * Emitted when the ability to overwrite text changes, via [[EditSession.setOverwrite]].
+ *
+ * @event changeOverwrite
+ **/
+/**
+ * Emitted when the gutter changes, either by setting or removing breakpoints, or when the gutter decorations change.
+ *
+ * @event changeBreakpoint
+ **/
+/**
+ * Emitted when a front marker changes.
+ *
+ * @event changeFrontMarker
+ **/
+/**
+ * Emitted when a back marker changes.
+ *
+ * @event changeBackMarker
+ **/
+/**
+ * Emitted when an annotation changes, like through [[EditSession.setAnnotations]].
+ *
+ * @event changeAnnotation
+ **/
+/**
+ * Emitted when a background tokenizer asynchronously processes new rows.
+ * @event tokenizerUpdate
+ *
+ * @param {Object} e An object containing one property, `"data"`, that contains information about the changing rows
+ *
+ **/
+/** 
+ * Emitted when the mode is loaded.
+ *
+ * @event loadMode
+ *
+ **/
+/** 
+ * Emitted when the current mode changes.
+ *
+ * @event changeMode
+ *
+ **/
+/** 
+ * Emitted when the wrap mode changes.
+ *
+ * @event changeWrapMode
+ *
+ **/
+/** 
+ * Emitted when the wrapping limit changes.
+ *
+ * @event changeWrapLimit
+ *
+ **/
+/**
+ * Emitted when a code fold is added or removed.
+ *
+ * @event changeFold
  *
  **/
+ /**
+ * Emitted when the scroll top changes.
+ * @event changeScrollTop
+ *
+ * @param {Number} scrollTop The new scroll top value
+ **/
+/**
+ * Emitted when the scroll left changes.
+ * @event changeScrollLeft
+ *
+ * @param {Number} scrollLeft The new scroll left value
+ **/
+
 
 /**
- * new EditSession(text, mode)
- * - text (Document | String): If `text` is a `Document`, it associates the `EditSession` with it. Otherwise, a new `Document` is created, with the initial text
- * - mode (TextMode): The inital language mode to use for the document
  *
  * Sets up a new `EditSession` and associates it with the given `Document` and `TextMode`.
+ * @param {Document | String} text If `text` is a `Document`, it associates the `EditSession` with it. Otherwise, a new `Document` is created, with the initial text
+ *
+ * @param {TextMode} mode The inital language mode to use for the document
  *
+ * @constructor
  **/
 
 var EditSession = function(text, mode) {
-    this.$modified = true;
     this.$breakpoints = [];
+    this.$decorations = [];
     this.$frontMarkers = {};
     this.$backMarkers = {};
     this.$markerId = 1;
-    this.$resetRowCache(0);
-    this.$wrapData = [];
-    this.$foldData = [];
-    this.$rowLengthCache = [];
     this.$undoSelect = true;
+    
+    this.$foldData = [];
     this.$foldData.toString = function() {
         var str = "";
         this.forEach(function(foldLine) {
@@ -87,12 +166,13 @@ var EditSession = function(text, mode) {
         });
         return str;
     }
+    this.on("changeFold", this.onChangeFold.bind(this));
+    this.$onChange = this.onChange.bind(this);
+    
+    if (typeof text != "object" || !text.getLine)
+        text = new Document(text);
 
-    if (typeof text == "object" && text.getLine) {
-        this.setDocument(text);
-    } else {
-        this.setDocument(new Document(text));
-    }
+    this.setDocument(text);
 
     this.selection = new Selection(this);
     this.setMode(mode);
@@ -104,51 +184,44 @@ var EditSession = function(text, mode) {
     oop.implement(this, EventEmitter);
 
     /**
-     * EditSession.setDocument(doc)
-     * - doc (Document): The new `Document` to use
-     *
      * Sets the `EditSession` to point to a new `Document`. If a `BackgroundTokenizer` exists, it also points to `doc`.
      *
+     * @param {Document} doc The new `Document` to use
+     *
      **/
     this.setDocument = function(doc) {
         if (this.doc)
-            throw new Error("Document is already set");
+            this.doc.removeListener("change", this.$onChange);
 
         this.doc = doc;
-        doc.on("change", this.onChange.bind(this));
-        this.on("changeFold", this.onChangeFold.bind(this));
+        doc.on("change", this.$onChange);
 
-        if (this.bgTokenizer) {
+        if (this.bgTokenizer)
             this.bgTokenizer.setDocument(this.getDocument());
-            this.bgTokenizer.start(0);
-        }
+
+        this.resetCaches();
     };
 
     /**
-     * EditSession.getDocument() -> Document
-     *
      * Returns the `Document` associated with this session.
-     *
+     * @return {Document} 
      **/
     this.getDocument = function() {
         return this.doc;
     };
 
-    /** internal, hide
-     * EditSession.$resetRowCache(row)
-     * - row (Number): The row to work with
-     *
-     *
+    /** 
+     * @param {Number} row The row to work with
      *
      **/
-    this.$resetRowCache = function(docRrow) {
-        if (!docRrow) {
+    this.$resetRowCache = function(docRow) {
+        if (!docRow) {
             this.$docRowCache = [];
             this.$screenRowCache = [];
             return;
         }
 
-        var i = this.$getRowCacheIndex(this.$docRowCache, docRrow) + 1;
+        var i = this.$getRowCacheIndex(this.$docRowCache, docRow) + 1;
         var l = this.$docRowCache.length;
         this.$docRowCache.splice(i, l);
         this.$screenRowCache.splice(i, l);
@@ -174,22 +247,20 @@ var EditSession = function(text, mode) {
         return low && low -1;
     };
 
-    /**
-    * EditSession@onChangeFold(e)
-    *
-    * Emitted when a code fold changes its state.
-    *
-    **/
+    this.resetCaches = function() {
+        this.$modified = true;
+        this.$wrapData = [];
+        this.$rowLengthCache = [];
+        this.$resetRowCache(0);
+        if (this.bgTokenizer)
+            this.bgTokenizer.start(0);
+    };
+
     this.onChangeFold = function(e) {
         var fold = e.data;
         this.$resetRowCache(fold.start.row);
     };
 
-    /**
-    * EditSession@onChange(e)
-    *
-    * Emitted when the document changes.
-    **/
     this.onChange = function(e) {
         var delta = e.data;
         this.$modified = true;
@@ -214,10 +285,10 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.setValue(text)
-    * - text (String): The new text to place
-    *
     * Sets the session text.
+    * @param {String} text The new text to place
+    *
+    *
     *
     **/
     this.setValue = function(text) {
@@ -232,17 +303,17 @@ var EditSession = function(text, mode) {
         this.getUndoManager().reset();
     };
 
-    /** alias of: EditSession.toString
-    * EditSession.getValue() -> String
-    *
+    /** 
     * Returns the current [[Document `Document`]] as a string.
+    * @method toString
+    * @alias EditSession.getValue 
     *
     **/
-    /** alias of: EditSession.getValue
-    * EditSession.toString() -> String
-    *
+    
+    /** 
     * Returns the current [[Document `Document`]] as a string.
-    *
+    * @method getValue
+    * @alias EditSession.toString 
     **/
     this.getValue =
     this.toString = function() {
@@ -250,30 +321,27 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getSelection() -> String
-    *
     * Returns the string of the current selection.
     **/
     this.getSelection = function() {
         return this.selection;
     };
 
-    /** related to: BackgroundTokenizer.getState
-     * EditSession.getState(row) -> Array
-     * - row (Number): The row to start at
-     *
+    /** 
      * {:BackgroundTokenizer.getState}
+     * @param {Number} row The row to start at
      *
+     * @related BackgroundTokenizer.getState
      **/
     this.getState = function(row) {
         return this.bgTokenizer.getState(row);
     };
 
-    /** related to: BackgroundTokenizer.getTokens
-    * EditSession.getTokens(row) -> Array
-     * - row (Number): The row to start at
-     *
+    /** 
      * Starts tokenizing at the row indicated. Returns a list of objects of the tokenized rows.
+     * @param {Number} row The row to start at
+     *
+     *
      *
      **/
     this.getTokens = function(row) {
@@ -281,11 +349,11 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getTokenAt(row, column) -> Array
-    * - row (Number): The row number to retrieve from
-    * - column (Number): The column number to retrieve from
+    * Returns an object indicating the token at the current row. The object has two properties: `index` and `start`.
+    * @param {Number} row The row number to retrieve from
+    * @param {Number} column The column number to retrieve from
+    *
     *
-    * Returns an array of tokens at the indicated row and column.
     **/
     this.getTokenAt = function(row, column) {
         var tokens = this.bgTokenizer.getTokens(row);
@@ -308,18 +376,11 @@ var EditSession = function(text, mode) {
         return token;
     };
 
-    this.highlight = function(re) {
-        if (!this.$searchHighlight) {
-            var highlight = new SearchHighlight(null, "ace_selected_word", "text");
-            this.$searchHighlight = this.addDynamicMarker(highlight);
-        }
-        this.$searchHighlight.setRegexp(re);
-    }
     /**
-    * EditSession.setUndoManager(undoManager)
-    * - undoManager (UndoManager): The new undo manager
-    *
     * Sets the undo manager.
+    * @param {UndoManager} undoManager The new undo manager
+    *
+    *
     **/
     this.setUndoManager = function(undoManager) {
         this.$undoManager = undoManager;
@@ -332,11 +393,7 @@ var EditSession = function(text, mode) {
 
         if (undoManager) {
             var self = this;
-    /** internal, hide
-    * EditSession.$syncInformUndoManager()
-    *
-    *
-    **/
+
             this.$syncInformUndoManager = function() {
                 self.$informUndoManager.cancel();
 
@@ -377,17 +434,13 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getUndoManager() -> UndoManager
-    *
     * Returns the current undo manager.
     **/
     this.getUndoManager = function() {
         return this.$undoManager || this.$defaultUndoManager;
-    },
+    };
 
     /**
-    * EditSession.getTabString() -> String
-    *
     * Returns the current value for tabs. If the user is using soft tabs, this will be a series of spaces (defined by [[EditSession.getTabSize `getTabSize()`]]); otherwise it's simply `'\t'`.
     **/
     this.getTabString = function() {
@@ -400,10 +453,10 @@ var EditSession = function(text, mode) {
 
     this.$useSoftTabs = true;
     /**
-    * EditSession.setUseSoftTabs(useSoftTabs)
-    * - useSoftTabs (Boolean): Value indicating whether or not to use soft tabs
-    *
     * Pass `true` to enable the use of soft tabs. Soft tabs means you're using spaces instead of the tab character (`'\t'`).
+    * @param {Boolean} useSoftTabs Value indicating whether or not to use soft tabs
+    *
+    *
     *
     **/
     this.setUseSoftTabs = function(useSoftTabs) {
@@ -413,10 +466,8 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getUseSoftTabs() -> Boolean
-    *
     * Returns `true` if soft tabs are being used, `false` otherwise.
-    *
+    * @returns {Boolean}
     **/
     this.getUseSoftTabs = function() {
         return this.$useSoftTabs;
@@ -424,10 +475,10 @@ var EditSession = function(text, mode) {
 
     this.$tabSize = 4;
     /**
-    * EditSession.setTabSize(tabSize)
-    * - tabSize (Number): The new tab size
-    *
     * Set the number of spaces that define a soft tab; for example, passing in `4` transforms the soft tabs to be equivalent to four spaces. This function also emits the `changeTabSize` event.
+    * @param {Number} tabSize The new tab size
+    *
+    *
     **/
     this.setTabSize = function(tabSize) {
         if (isNaN(tabSize) || this.$tabSize === tabSize) return;
@@ -439,8 +490,6 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getTabSize() -> Number
-    *
     * Returns the current tab size.
     **/
     this.getTabSize = function() {
@@ -448,10 +497,10 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.isTabStop(position) -> Boolean
-    * - position (Object): The position to check
-    *
     * Returns `true` if the character at the position is a soft tab.
+    * @param {Object} position The position to check
+    *
+    *
     **/
     this.isTabStop = function(position) {
         return this.$useSoftTabs && (position.column % this.$tabSize == 0);
@@ -459,10 +508,12 @@ var EditSession = function(text, mode) {
 
     this.$overwrite = false;
     /**
-    * EditSession.setOverwrite(overwrite)
-    * - overwrite (Boolean): Defines wheter or not to set overwrites
+    * Pass in `true` to enable overwrites in your session, or `false` to disable. 
+    *
+    * If overwrites is enabled, any text you enter will type over any text after it. If the value of `overwrite` changes, this function also emites the `changeOverwrite` event.
+    *
+    * @param {Boolean} overwrite Defines wheter or not to set overwrites
     *
-    * Pass in `true` to enable overwrites in your session, or `false` to disable. If overwrites is enabled, any text you enter will type over any text after it. If the value of `overwrite` changes, this function also emites the `changeOverwrite` event.
     *
     **/
     this.setOverwrite = function(overwrite) {
@@ -473,8 +524,6 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getOverwrite() -> Boolean
-    *
     * Returns `true` if overwrites are enabled; `false` otherwise.
     **/
     this.getOverwrite = function() {
@@ -482,8 +531,6 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.toggleOverwrite()
-    *
     * Sets the value of overwrite to the opposite of whatever it currently is.
     **/
     this.toggleOverwrite = function() {
@@ -491,32 +538,55 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getBreakpoints() -> Array
+    * Adds `className` to the `row`, to be used for CSS stylings and whatnot.
+    * @param {Number} row The row number
+    * @param {String} className The class to add
+    *
+    *
+    **/
+    this.addGutterDecoration = function(row, className) {
+        if (!this.$decorations[row])
+            this.$decorations[row] = "";
+        this.$decorations[row] += " " + className;
+        this._emit("changeBreakpoint", {});
+    };
+
+    /**
+    * Removes `className` from the `row`.
+    * @param {Number} row The row number
+    * @param {String} className The class to add
+    *
     *
+    **/
+    this.removeGutterDecoration = function(row, className) {
+        this.$decorations[row] = (this.$decorations[row] || "").replace(" " + className, "");
+        this._emit("changeBreakpoint", {});
+    };
+    
+    /**
     * Returns an array of numbers, indicating which rows have breakpoints.
+    * @returns [Number]
     **/
     this.getBreakpoints = function() {
         return this.$breakpoints;
     };
 
     /**
-    * EditSession.setBreakpoints(rows)
-    * - rows (Array): An array of row indicies
-    *
     * Sets a breakpoint on every row number given by `rows`. This function also emites the `'changeBreakpoint'` event.
+    * @param {Number} rows An array of row indicies
+    *
+    *
     *
     **/
     this.setBreakpoints = function(rows) {
         this.$breakpoints = [];
         for (var i=0; i<rows.length; i++) {
-            this.$breakpoints[rows[i]] = true;
+            this.$breakpoints[rows[i]] = "ace_breakpoint";
         }
         this._emit("changeBreakpoint", {});
     };
 
     /**
-    * EditSession.clearBreakpoints()
-    *
     * Removes all breakpoints on the rows. This function also emites the `'changeBreakpoint'` event.
     **/
     this.clearBreakpoints = function() {
@@ -525,21 +595,27 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.setBreakpoint(row)
-    * - row (Number): A row index
-    *
     * Sets a breakpoint on the row number given by `rows`. This function also emites the `'changeBreakpoint'` event.
+    * @param {Number} row A row index
+    * @param {String} className Class of the breakpoint
+    *
+    *
     **/
-    this.setBreakpoint = function(row) {
-        this.$breakpoints[row] = true;
+    this.setBreakpoint = function(row, className) {
+        if (className === undefined)
+            className = "ace_breakpoint";
+        if (className)
+            this.$breakpoints[row] = className;
+        else
+            delete this.$breakpoints[row];
         this._emit("changeBreakpoint", {});
     };
 
     /**
-    * EditSession.clearBreakpoint(row)
-    * - row (Number): A row index
-    *
     * Removes a breakpoint on the row number given by `rows`. This function also emites the `'changeBreakpoint'` event.
+    * @param {Number} row A row index
+    *
+    *
     **/
     this.clearBreakpoint = function(row) {
         delete this.$breakpoints[row];
@@ -547,14 +623,14 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.addMarker(range, clazz, type = "line", inFront) -> Number
-    * - range (Range): Define the range of the marker
-    * - clazz (String): Set the CSS class for the marker
-    * - type (Function | String): Identify the type of the marker
-    * - inFront (Boolean): Set to `true` to establish a front marker
-    *
     * Adds a new marker to the given `Range`. If `inFront` is `true`, a front marker is defined, and the `'changeFrontMarker'` event fires; otherwise, the `'changeBackMarker'` event fires.
+    * @param {Range} range Define the range of the marker
+    * @param {String} clazz Set the CSS class for the marker
+    * @param {Function | String} type Identify the type of the marker
+    * @param {Boolean} inFront Set to `true` to establish a front marker
     *
+    *
+    * @return Number
     **/
     this.addMarker = function(range, clazz, type, inFront) {
         var id = this.$markerId++;
@@ -580,11 +656,13 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.addDynamicMarker(marker) -> {update}
-    * - marker : object with update method
-    * - inFront (Boolean): Set to `true` to establish a front marker
-    *
-    **/
+     * Adds a dynamic marker to the session.
+     * @param {Object} marker object with update method
+     * @param {Boolean} inFront Set to `true` to establish a front marker
+     *
+     * 
+     * @return Object The added marker
+     **/
     this.addDynamicMarker = function(marker, inFront) {
         if (!marker.update)
             return;
@@ -604,10 +682,10 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.removeMarker(markerId)
-    * - markerId (Number): A number representing a marker
-    *
     * Removes the marker with the specified ID. If this marker was in front, the `'changeFrontMarker'` event is emitted. If the marker was in the back, the `'changeBackMarker'` event is emitted.
+    * @param {Number} markerId A number representing a marker
+    *
+    *
     *
     **/
     this.removeMarker = function(markerId) {
@@ -623,16 +701,39 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getMarkers(inFront) -> Array
-    * - inFront (Boolean): If `true`, indicates you only want front markers; `false` indicates only back markers
-    *
     * Returns an array containing the IDs of all the markers, either front or back.
+    * @param {Boolean} inFront If `true`, indicates you only want front markers; `false` indicates only back markers
     *
+    * @returns {Array}
     **/
     this.getMarkers = function(inFront) {
         return inFront ? this.$frontMarkers : this.$backMarkers;
     };
 
+    this.highlight = function(re) {
+        if (!this.$searchHighlight) {
+            var highlight = new SearchHighlight(null, "ace_selected-word", "text");
+            this.$searchHighlight = this.addDynamicMarker(highlight);
+        }
+        this.$searchHighlight.setRegexp(re);
+    }
+    
+    // experimental
+    this.highlightLines = function(startRow, endRow, clazz, inFront) {
+        if (typeof endRow != "number") {
+            clazz = endRow;
+            endRow = startRow;
+        }
+        if (!clazz)
+            clazz = "ace_step";
+        
+        var range = new Range(startRow, 0, endRow, Infinity);
+        
+        var id = this.addMarker(range, clazz, "fullLine", inFront);
+        range.id = id;
+        return range;
+    };
+   
     /*
      * Error:
      *  {
@@ -643,36 +744,24 @@ var EditSession = function(text, mode) {
      *  }
      */
     /**
-    * EditSession.setAnnotations(annotations)
-    * - annotations (Array): A list of annotations
-    *
     * Sets annotations for the `EditSession`. This functions emits the `'changeAnnotation'` event.
+    * @param {Array} annotations A list of annotations
+    *
     **/
     this.setAnnotations = function(annotations) {
-        this.$annotations = {};
-        for (var i=0; i<annotations.length; i++) {
-            var annotation = annotations[i];
-            var row = annotation.row;
-            if (this.$annotations[row])
-                this.$annotations[row].push(annotation);
-            else
-                this.$annotations[row] = [annotation];
-        }
+        this.$annotations = annotations;
         this._emit("changeAnnotation", {});
     };
 
     /**
-    * EditSession.getAnnotations() -> Object
-    *
     * Returns the annotations for the `EditSession`.
+    * @returns {Object}
     **/
     this.getAnnotations = function() {
-        return this.$annotations || {};
+        return this.$annotations || [];
     };
 
     /**
-    * EditSession.clearAnnotations()
-    *
     * Clears all the annotations for this session. This function also triggers the `'changeAnnotation'` event.
     **/
     this.clearAnnotations = function() {
@@ -680,11 +769,10 @@ var EditSession = function(text, mode) {
         this._emit("changeAnnotation", {});
     };
 
-    /** internal, hide
-    * EditSession.$detectNewLine(text)
-    * - text (String): A block of text
-    *
+    /** 
     * If `text` contains either the newline (`\n`) or carriage-return ('\r') characters, `$autoNewLine` stores that value.
+    * @param {String} text A block of text
+    *
     *
     **/
     this.$detectNewLine = function(text) {
@@ -697,12 +785,11 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getWordRange(row, column) -> Range
-    * - row (Number): The row to start at
-    * - column (Number): The column to start at
-    *
     * Given a starting row and column, this method returns the `Range` of the first word boundary it finds.
+    * @param {Number} row The row to start at
+    * @param {Number} column The column to start at
     *
+    * @returns {Range}
     **/
     this.getWordRange = function(row, column) {
         var line = this.getLine(row);
@@ -739,11 +826,11 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getAWordRange(row, column) -> Range
-    * - row (Number): The row number to start from
-    * - column (Number): The column number to start from
-    *
     * Gets the range of a word, including its right whitespace.
+    * @param {Number} row The row number to start from
+    * @param {Number} column The column number to start from
+    *
+    * @return Range
     **/
     this.getAWordRange = function(row, column) {
         var wordRange = this.getWordRange(row, column);
@@ -755,20 +842,22 @@ var EditSession = function(text, mode) {
         return wordRange;
     };
 
-    /** related to: Document.setNewLineMode
-    * EditSession.setNewLineMode(newLineMode)
-    * - newLineMode (String): {:Document.setNewLineMode.param}
-    *
+    /** 
     * {:Document.setNewLineMode.desc}
+    * @param {String} newLineMode {:Document.setNewLineMode.param}
+    *
+    *
+    * @related Document.setNewLineMode
     **/
     this.setNewLineMode = function(newLineMode) {
         this.doc.setNewLineMode(newLineMode);
     };
 
-    /** related to: Document.getNewLineMode
-    * EditSession.getNewLineMode() -> String
+    /** 
     *
     * Returns the current new line mode.
+    * @returns String
+    * @related Document.getNewLineMode
     **/
     this.getNewLineMode = function() {
         return this.doc.getNewLineMode();
@@ -777,10 +866,8 @@ var EditSession = function(text, mode) {
     this.$useWorker = true;
 
     /**
-    * EditSession.setUseWorker(useWorker)
-    * - useWorker (Boolean): Set to `true` to use a worker
-    *
     * Identifies if you want to use a worker for the `EditSession`.
+    * @param {Boolean} useWorker Set to `true` to use a worker
     *
     **/
     this.setUseWorker = function(useWorker) {
@@ -795,8 +882,6 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getUseWorker() -> Boolean
-    *
     * Returns `true` if workers are being used.
     **/
     this.getUseWorker = function() {
@@ -804,8 +889,6 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession@onReloadTokenizer(e)
-    *
     * Reloads all the tokens on the current session. This function calls [[BackgroundTokenizer.start `BackgroundTokenizer.start ()`]] to all the rows; it also emits the `'tokenizerUpdate'` event.
     **/
     this.onReloadTokenizer = function(e) {
@@ -835,7 +918,7 @@ var EditSession = function(text, mode) {
         if (!this.$mode)
             this.$setModePlaceholder();
 
-        fetch(function() {
+        fetch(mode, function() {
             require([mode], done);
         });
 
@@ -852,13 +935,11 @@ var EditSession = function(text, mode) {
             callback(_self.$modes[mode]);
         }
 
-        function fetch(callback) {
+        function fetch(name, callback) {
             if (!config.get("packaged"))
                 return callback();
 
-            var base = mode.split("/").pop();
-            var filename = config.get("modePath") + "/mode-" + base + ".js";
-            net.loadScript(filename, callback);
+            net.loadScript(config.moduleUrl(name, "mode"), callback);
         }
     };
 
@@ -882,10 +963,8 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.setMode(mode)
-    * - mode (TextMode): Set a new text mode
-    *
     * Sets a new text mode for the `EditSession`. This method also emits the `'changeMode'` event. If a [[BackgroundTokenizer `BackgroundTokenizer`]] is set, the `'tokenizerUpdate'` event is also emitted.
+    * @param {TextMode} mode Set a new text mode
     *
     **/
     this.$mode = null;
@@ -945,11 +1024,7 @@ var EditSession = function(text, mode) {
         this._emit("changeMode");
     };
 
-    /** internal, hide
-    * EditSession.stopWorker()
-    *
-    *
-    **/
+
     this.$stopWorker = function() {
         if (this.$worker)
             this.$worker.terminate();
@@ -957,11 +1032,7 @@ var EditSession = function(text, mode) {
         this.$worker = null;
     };
 
-    /** internal, hide
-    * EditSession.$startWorker()
-    *
-    *
-    **/
+
     this.$startWorker = function() {
         if (typeof Worker !== "undefined" && !require.noWorker) {
             try {
@@ -977,9 +1048,8 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getMode() -> TextMode
-    *
     * Returns the current text mode.
+    * @returns {TextMode} The current text mode
     **/
     this.getMode = function() {
         return this.$mode;
@@ -987,10 +1057,9 @@ var EditSession = function(text, mode) {
 
     this.$scrollTop = 0;
     /**
-    * EditSession.setScrollTop(scrollTop)
-    * - scrollTop (Number): The new scroll top value
-    *
     * This function sets the scroll top value. It also emits the `'changeScrollTop'` event.
+    * @param {Number} scrollTop The new scroll top value
+    *
     **/
     this.setScrollTop = function(scrollTop) {
         scrollTop = Math.round(Math.max(0, scrollTop));
@@ -1002,9 +1071,8 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getScrollTop() -> Number
-    *
     * [Returns the value of the distance between the top of the editor and the topmost part of the visible content.]{: #EditSession.getScrollTop}
+    * @returns {Number}
     **/
     this.getScrollTop = function() {
         return this.$scrollTop;
@@ -1012,8 +1080,6 @@ var EditSession = function(text, mode) {
 
     this.$scrollLeft = 0;
     /**
-    * EditSession.setScrollLeft(scrollLeft)
-    *
     * [Sets the value of the distance between the left of the editor and the leftmost part of the visible content.]{: #EditSession.setScrollLeft}
     **/
     this.setScrollLeft = function(scrollLeft) {
@@ -1026,18 +1092,16 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getScrollLeft() -> Number
-    *
     * [Returns the value of the distance between the left of the editor and the leftmost part of the visible content.]{: #EditSession.getScrollLeft}
+    * @returns {Number}
     **/
     this.getScrollLeft = function() {
         return this.$scrollLeft;
     };
 
     /**
-    * EditSession.getScreenWidth() -> Number
-    *
     * Returns the width of the screen.
+    * @returns {Number}
     **/
     this.getScreenWidth = function() {
         this.$computeWidth();
@@ -1063,7 +1127,7 @@ var EditSession = function(text, mode) {
                 if (i > foldStart) {
                     i = foldLine.end.row + 1;
                     if (i >= len)
-                        break
+                        break;
                     foldLine = this.$foldData[foldIndex++];
                     foldStart = foldLine ? foldLine.start.row : Infinity;
                 }
@@ -1078,55 +1142,53 @@ var EditSession = function(text, mode) {
         }
     };
 
-    /** related to: Document.getLine
-    * EditSession.getLine(row) -> String
-    * - row (Number): The row to retrieve from
+    /** 
+     * Returns a verbatim copy of the given line as it is in the document
+     * @param {Number} row The row to retrieve from
+     *
     *
-    * Returns a verbatim copy of the given line as it is in the document
+     * @returns {String}
     *
     **/
     this.getLine = function(row) {
         return this.doc.getLine(row);
     };
 
-    /** related to: Document.getLines
-    * EditSession.getLines(firstRow, lastRow) -> Array
-    * - firstRow (Number): The first row index to retrieve
-    * - lastRow (Number): The final row index to retrieve
-    *
-    * Returns an array of strings of the rows between `firstRow` and `lastRow`. This function is inclusive of `lastRow`.
-    *
-    **/
+    /** 
+     * Returns an array of strings of the rows between `firstRow` and `lastRow`. This function is inclusive of `lastRow`.
+     * @param {Number} firstRow The first row index to retrieve
+     * @param {Number} lastRow The final row index to retrieve
+     *
+     * @returns [String]
+     *
+     **/
     this.getLines = function(firstRow, lastRow) {
         return this.doc.getLines(firstRow, lastRow);
     };
 
-    /** related to: Document.getLength
-    * EditSession.getLength()-> Number
-    *
-    * Returns the number of rows in the document.
-    **/
+    /** 
+     * Returns the number of rows in the document.
+     * @returns {Number}
+     **/
     this.getLength = function() {
         return this.doc.getLength();
     };
 
-    /** related to: Document.getTextRange
-    * EditSession.getTextRange(range) -> Array
-    * - range (String): The range to work with
-    *
-    * {:Document.getTextRange.desc}
-    **/
+    /** 
+     * {:Document.getTextRange.desc}
+     * @param {Range} range The range to work with
+     *
+     * @returns {Range}
+     **/
     this.getTextRange = function(range) {
         return this.doc.getTextRange(range || this.selection.getRange());
     };
 
-    /** related to: Document.insert
-    * EditSession.insert(position, text) -> Number
-    * - position (Number): The position to start inserting at
-    * - text (String): A chunk of text to insert
-    * + (Number): The position of the last line of `text`. If the length of `text` is 0, this function simply returns `position`.
-    *
+    /** 
     * Inserts a block of `text` and the indicated `position`.
+     * @param {Object} position The position {row, column} to start inserting at
+     * @param {String} text A chunk of text to insert
+     * @returns {Object} The position of the last line of `text`. If the length of `text` is 0, this function simply returns `position`.
     *
     *
     **/
@@ -1134,13 +1196,12 @@ var EditSession = function(text, mode) {
         return this.doc.insert(position, text);
     };
 
-    /** related to: Document.remove
-    * EditSession.remove(range) -> Object
-    * - range (Range): A specified Range to remove
-    * + (Object): The new `start` property of the range, which contains `startRow` and `startColumn`. If `range` is empty, this function returns the unmodified value of `range.start`.
-    *
+    /** 
     * Removes the `range` from the document.
+     * @param {Range} range A specified Range to remove
+     * @returns {Object} The new `start` property of the range, which contains `startRow` and `startColumn`. If `range` is empty, this function returns the unmodified value of `range.start`.
     *
+     * @related Document.remove
     *
     **/
     this.remove = function(range) {
@@ -1148,11 +1209,12 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.undoChanges(deltas, dontSelect) -> Range
-    * - deltas (Array): An array of previous changes
-    * - dontSelect (Boolean): [If `true`, doesn't select the range of where the change occured]{: #dontSelect}
+     * Reverts previous changes to your document.
+     * @param {Array} deltas An array of previous changes
+     * @param {Boolean} dontSelect [If `true`, doesn't select the range of where the change occured]{: #dontSelect}
     *
-    * Reverts previous changes to your document.
+     * 
+     * @returns {Range}
     **/
     this.undoChanges = function(deltas, dontSelect) {
         if (!deltas.length)
@@ -1181,11 +1243,12 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.redoChanges(deltas, dontSelect) -> Range
-    * - deltas (Array): An array of previous changes
-    * - dontSelect (Boolean): {:dontSelect}
+     * Re-implements a previously undone change to your document.
+     * @param {Array} deltas An array of previous changes
+     * @param {Boolean} dontSelect {:dontSelect}
+     *
     *
-    * Re-implements a previously undone change to your document.
+     * @returns {Range}
     **/
     this.redoChanges = function(deltas, dontSelect) {
         if (!deltas.length)
@@ -1210,20 +1273,14 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.setUndoSelect(enable)
-    * - enable (Boolean): If `true`, selects the range of the reinserted change
+     * Enables or disables highlighting of the range where an undo occured.
+     * @param {Boolean} enable If `true`, selects the range of the reinserted change
     *
-    * ENables or disables highlighting of the range where an undo occured.
     **/
     this.setUndoSelect = function(enable) {
         this.$undoSelect = enable;
     };
 
-    /** internal, hide
-    * EditSession.$getUndoSelection(deltas, isUndo, lastUndoRange) -> Range
-    *
-    *
-    **/
     this.$getUndoSelection = function(deltas, isUndo, lastUndoRange) {
         function isInsert(delta) {
             var insert =
@@ -1276,20 +1333,24 @@ var EditSession = function(text, mode) {
         }
 
         return range;
-    },
-
-    /** related to: Document.replace
-    * EditSession.replace(range, text) -> Object
-    * - range (Range): A specified Range to replace
-    * - text (String): The new text to use as a replacement
-    * + (Object): Returns an object containing the final row and column, like this:<br/>
-    * ```{row: endRow, column: 0}```<br/>
-    * If the text and range are empty, this function returns an object containing the current `range.start` value.<br/>
+    };
+
+    /** 
+    * Replaces a range in the document with the new `text`.
+    *
+    * @param {Range} range A specified Range to replace
+    * @param {String} text The new text to use as a replacement
+    * @returns {Object} An object containing the final row and column, like this:   
+    * ```
+    * {row: endRow, column: 0}
+    * ```  
+    * If the text and range are empty, this function returns an object containing the current `range.start` value.  
     * If the text is the exact same as what currently exists, this function returns an object containing the current `range.end` value.
     *
-    * Replaces a range in the document with the new `text`.
     *
     *
+    * @related Document.replace
+    *
     *
     **/
     this.replace = function(range, text) {
@@ -1297,13 +1358,13 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.moveText(fromRange, toPosition) -> Range
-    * - fromRange (Range): The range of text you want moved within the document
-    * - toPosition (Object): The location (row and column) where you want to move the text to
-    * + (Range): The new range where the text was moved to.
     * Moves a range of text from the given range to the given position. `toPosition` is an object that looks like this:
-    *
+     *  ```json
     *    { row: newRowLocation, column: newColumnLocation }
+     *  ```
+     * @param {Range} fromRange The range of text you want moved within the document
+     * @param {Object} toPosition The location (row and column) where you want to move the text to
+     * @returns {Range} The new range where the text was moved to.
     *
     *
     *
@@ -1339,14 +1400,13 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.indentRows(startRow, endRow, indentString)
-    * - startRow (Number): Starting row
-    * - endRow (Number): Ending row
-    * - indentString (String): The indent token
-    *
     * Indents all the rows, from `startRow` to `endRow` (inclusive), by prefixing each row with the token in `indentString`.
     *
     * If `indentString` contains the `'\t'` character, it's replaced by whatever is defined by [[EditSession.getTabString `getTabString()`]].
+    * @param {Number} startRow Starting row
+    * @param {Number} endRow Ending row
+    * @param {String} indentString The indent token
+    *
     *
     **/
     this.indentRows = function(startRow, endRow, indentString) {
@@ -1356,10 +1416,9 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.outdentRows(range)
-    * - range (Range): A range of rows
-    *
     * Outdents all the rows defined by the `start` and `end` properties of `range`.
+    * @param {Range} range A range of rows
+    *
     *
     **/
     this.outdentRows = function (range) {
@@ -1386,14 +1445,13 @@ var EditSession = function(text, mode) {
         }
     };
 
-    /** related to: Document.insertLines
-    * EditSession.moveLinesUp(firstRow, lastRow) -> Number
-    * - firstRow (Number): The starting row to move up
-    * - lastRow (Number): The final row to move up
-    * + (Number): If `firstRow` is less-than or equal to 0, this function returns 0. Otherwise, on success, it returns -1.
-    *
+    /**  
     * Shifts all the lines in the document up one, starting from `firstRow` and ending at `lastRow`.
+    * @param {Number} firstRow The starting row to move up
+    * @param {Number} lastRow The final row to move up
+    * @returns {Number} If `firstRow` is less-than or equal to 0, this function returns 0. Otherwise, on success, it returns -1.
     *
+    * @related Document.insertLines
     *
     **/
     this.moveLinesUp = function(firstRow, lastRow) {
@@ -1404,14 +1462,15 @@ var EditSession = function(text, mode) {
         return -1;
     };
 
-    /** related to: Document.insertLines
-    * EditSession.moveLinesDown(firstRow, lastRow) -> Number
-    * - firstRow (Number): The starting row to move down
-    * - lastRow (Number): The final row to move down
-    * + (Number): If `firstRow` is less-than or equal to 0, this function returns 0. Otherwise, on success, it returns -1.
+    /** 
+    * Shifts all the lines in the document down one, starting from `firstRow` and ending at `lastRow`.
+    * @param {Number} firstRow The starting row to move down
+    * @param {Number} lastRow The final row to move down
+    * @returns {Number} If `firstRow` is less-than or equal to 0, this function returns 0. Otherwise, on success, it returns -1.
     *
     *
     *
+    * @related Document.insertLines
     **/
     this.moveLinesDown = function(firstRow, lastRow) {
         if (lastRow >= this.doc.getLength()-1) return 0;
@@ -1422,13 +1481,10 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.duplicateLines(firstRow, lastRow) -> Number
-    * - firstRow (Number): The starting row to duplicate
-    * - lastRow (Number): The final row to duplicate
-    * + (Number): Returns the number of new rows added; in other words, `lastRow - firstRow + 1`.
-    *
     * Duplicates all the text between `firstRow` and `lastRow`.
-    *
+    * @param {Number} firstRow The starting row to duplicate
+    * @param {Number} lastRow The final row to duplicate
+    * @returns {Number} Returns the number of new rows added; in other words, `lastRow - firstRow + 1`.
     *
     *
     **/
@@ -1480,7 +1536,7 @@ var EditSession = function(text, mode) {
     this.$clipRangeToDocument = function(range) {
         if (range.start.row < 0) {
             range.start.row = 0;
-            range.start.column = 0
+            range.start.column = 0;
         } else {
             range.start.column = this.$clipColumnToRow(
                 range.start.row,
@@ -1510,10 +1566,10 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.setUseWrapMode(useWrapMode)
-    * - useWrapMode (Boolean): Enable (or disable) wrap mode
+     * Sets whether or not line wrapping is enabled. If `useWrapMode` is different than the current value, the `'changeWrapMode'` event is emitted.
+     * @param {Boolean} useWrapMode Enable (or disable) wrap mode
+     *
     *
-    * Sets whether or not line wrapping is enabled. If `useWrapMode` is different than the current value, the `'changeWrapMode'` event is emitted.
     **/
     this.setUseWrapMode = function(useWrapMode) {
         if (useWrapMode != this.$useWrapMode) {
@@ -1536,9 +1592,8 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getUseWrapMode() -> Boolean
-    *
     * Returns `true` if wrap mode is being used; `false` otherwise.
+    * @returns {Boolean}
     **/
     this.getUseWrapMode = function() {
         return this.$useWrapMode;
@@ -1549,11 +1604,11 @@ var EditSession = function(text, mode) {
     // in that direction. Or set both parameters to the same number to pin
     // the limit to that value.
     /**
-    * EditSession.setWrapLimitRange(min, max)
-    * - min (Number): The minimum wrap value (the left side wrap)
-    * - max (Number): The maximum wrap value (the right side wrap)
+     * Sets the boundaries of wrap. Either value can be `null` to have an unconstrained wrap, or, they can be the same number to pin the limit. If the wrap limits for `min` or `max` are different, this method also emits the `'changeWrapMode'` event.
+     * @param {Number} min The minimum wrap value (the left side wrap)
+     * @param {Number} max The maximum wrap value (the right side wrap)
+     *
     *
-    * Sets the boundaries of wrap. Either value can be `null` to have an unconstrained wrap, or, they can be the same number to pin the limit. If the wrap limits for `min` or `max` are different, this method also emits the `'changeWrapMode'` event.
     **/
     this.setWrapLimitRange = function(min, max) {
         if (this.$wrapLimitRange.min !== min || this.$wrapLimitRange.max !== max) {
@@ -1565,11 +1620,13 @@ var EditSession = function(text, mode) {
         }
     };
 
-    /** internal, hide
-    * EditSession.adjustWrapLimit(desiredLimit) -> Boolean
-    * - desiredLimit (Number): The new wrap limit
-    *
+    /** 
     * This should generally only be called by the renderer when a resize is detected.
+    * @param {Number} desiredLimit The new wrap limit
+    * @returns {Boolean}
+    *
+    * 
+    * @private
     **/
     this.adjustWrapLimit = function(desiredLimit) {
         var wrapLimit = this.$constrainWrapLimit(desiredLimit);
@@ -1578,7 +1635,7 @@ var EditSession = function(text, mode) {
             this.$modified = true;
             if (this.$useWrapMode) {
                 this.$updateWrapData(0, this.getLength() - 1);
-                this.$resetRowCache(0)
+                this.$resetRowCache(0);
                 this._emit("changeWrapLimit");
             }
             return true;
@@ -1586,11 +1643,6 @@ var EditSession = function(text, mode) {
         return false;
     };
 
-    /** internal, hide
-    * EditSession.$constrainWrapLimit(wrapLimit)
-    *
-    *
-    **/
     this.$constrainWrapLimit = function(wrapLimit) {
         var min = this.$wrapLimitRange.min;
         if (min)
@@ -1605,8 +1657,6 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getWrapLimit() -> Number
-    *
     * Returns the value of wrap limit.
     **/
     this.getWrapLimit = function() {
@@ -1614,12 +1664,11 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getWrapLimitRange() -> Object
-    *
     * Returns an object that defines the minimum and maximum of the wrap limit; it looks something like this:
     *
     *     { min: wrapLimitRange_min, max: wrapLimitRange_max }
     *
+    * @returns {Object}
     **/
     this.getWrapLimitRange = function() {
         // Avoid unexpected mutation by returning a copy
@@ -1629,11 +1678,6 @@ var EditSession = function(text, mode) {
         };
     };
 
-    /** internal, hide
-    * EditSession.$updateInternalDataOnChange()
-    *
-    *
-    **/
     this.$updateInternalDataOnChange = function(e) {
         var useWrapMode = this.$useWrapMode;
         var len;
@@ -1757,16 +1801,10 @@ var EditSession = function(text, mode) {
     };
 
     this.$updateRowLengthCache = function(firstRow, lastRow, b) {
-        //console.log(firstRow, lastRow, b)
         this.$rowLengthCache[firstRow] = null;
         this.$rowLengthCache[lastRow] = null;
-        //console.log(this.$rowLengthCache)
     };
 
-    /** internal, hide
-    * EditSession.$updateWrapData(firstRow, lastRow)
-    *
-    **/
     this.$updateWrapData = function(firstRow, lastRow) {
         var lines = this.doc.getAllLines();
         var tabSize = this.getTabSize();
@@ -1785,10 +1823,9 @@ var EditSession = function(text, mode) {
                 row ++;
             } else {
                 tokens = [];
-                foldLine.walk(
-                    function(placeholder, row, column, lastColumn) {
+                foldLine.walk(function(placeholder, row, column, lastColumn) {
                         var walkTokens;
-                        if (placeholder) {
+                        if (placeholder != null) {
                             walkTokens = this.$getDisplayTokens(
                                             placeholder, tokens.length);
                             walkTokens[0] = PLACEHOLDER_START;
@@ -1826,11 +1863,7 @@ var EditSession = function(text, mode) {
         TAB = 11,
         TAB_SPACE = 12;
 
-    /** internal, hide
-    * EditSession.$computeWrapSplits(tokens, wrapLimit) -> Array
-    *
-    *
-    **/
+
     this.$computeWrapSplits = function(tokens, wrapLimit) {
         if (tokens.length == 0) {
             return [];
@@ -1945,14 +1978,14 @@ var EditSession = function(text, mode) {
             addSplit(split);
         }
         return splits;
-    }
+    };
 
-    /** internal, hide
-    * EditSession.$getDisplayTokens(str, offset) -> Array
-    * - str (String): The string to check
-    * - offset (Number): The value to start at
-    *
+    /**
     * Given a string, returns an array of the display characters, including tabs and spaces.
+    * @param {String} str The string to check
+    * @param {Number} offset The value to start at
+    *
+    *
     **/
     this.$getDisplayTokens = function(str, offset) {
         var arr = [];
@@ -1983,18 +2016,18 @@ var EditSession = function(text, mode) {
             }
         }
         return arr;
-    }
+    };
 
-    /** internal, hide
-    * EditSession.$getStringScreenWidth(str, maxScreenColumn, screenColumn) -> [Number]
-    * - str (String): The string to calculate the screen width of
-    * - maxScreenColumn (Number):
-    * - screenColumn (Number):
-    * + ([Number]): Returns an `int[]` array with two elements:<br/>
+    /**
+     * Calculates the width of the string `str` on the screen while assuming that the string starts at the first column on the screen.
+    * @param {String} str The string to calculate the screen width of
+    * @param {Number} maxScreenColumn
+    * @param {Number} screenColumn
+    * @returns {[Number]} Returns an `int[]` array with two elements:<br/>
     * The first position indicates the number of columns for `str` on screen.<br/>
     * The second value contains the position of the document column that this function read until.
     *
-    * Calculates the width of the string `str` on the screen while assuming that the string starts at the first column on the screen.
+    *
     *
     *
     **/
@@ -2019,19 +2052,18 @@ var EditSession = function(text, mode) {
                 screenColumn += 1;
             }
             if (screenColumn > maxScreenColumn) {
-                break
+                break;
             }
         }
 
         return [screenColumn, column];
-    }
+    };
 
     /**
-    * EditSession.getRowLength(row) -> Number
-    * - row (Number): The row number to check
-    *
+    * Returns number of screenrows in a wrapped line.
+    * @param {Number} row The row number to check
     *
-    * Returns the length of the indicated row.
+    * @returns {Number}
     **/
     this.getRowLength = function(row) {
         if (!this.$useWrapMode || !this.$wrapData[row]) {
@@ -2039,44 +2071,36 @@ var EditSession = function(text, mode) {
         } else {
             return this.$wrapData[row].length + 1;
         }
-    }
+    };
 
-    /**
-    * EditSession.getRowHeight(config, row) -> Number
-    * - config (Object): An object containing a parameter indicating the `lineHeight`.
-    * - row (Number): The row number to check
+    /** 
+     * Returns the position (on screen) for the last character in the provided screen row.
+     * @param {Number} screenRow The screen row to check
     *
-    * Returns the height of the indicated row. This is mostly relevant for situations where wrapping occurs, and a single line spans across multiple rows.
-    *
-     **/
-    this.getRowHeight = function(config, row) {
-        return this.getRowLength(row) * config.lineHeight;
-    }
-
-    /** internal, hide, related to: EditSession.documentToScreenColumn
-    * EditSession.getScreenLastRowColumn(screenRow) -> Number
-    * - screenRow (Number): The screen row to check
     *
-    * Returns the column position (on screen) for the last character in the provided row.
+     * @related EditSession.documentToScreenColumn
     **/
     this.getScreenLastRowColumn = function(screenRow) {
-        var pos = this.screenToDocumentPosition(screenRow, Number.MAX_VALUE)
+        var pos = this.screenToDocumentPosition(screenRow, Number.MAX_VALUE);
         return this.documentToScreenColumn(pos.row, pos.column);
     };
 
-    /** internal, hide
-    * EditSession.getDocumentLastRowColumn(docRow, docColumn) -> Number
-    * - docRow (Number):
-    * - docColumn (Number):
+    /** 
+    * For the given document row and column, this returns the column position of the last screen row.
+    * @param {Number} docRow 
     *
+    * @param {Number} docColumn 
     **/
     this.getDocumentLastRowColumn = function(docRow, docColumn) {
         var screenRow = this.documentToScreenRow(docRow, docColumn);
         return this.getScreenLastRowColumn(screenRow);
     };
 
-    /** internal, hide
-    * EditSession.getDocumentLastRowColumnPosition(docRow, docColumn) -> Number
+    /** 
+    * For the given document row and column, this returns the document position of the last row.
+    * @param {Number} docRow 
+    * @param {Number} docColumn 
+    *
     *
     **/
     this.getDocumentLastRowColumnPosition = function(docRow, docColumn) {
@@ -2084,9 +2108,9 @@ var EditSession = function(text, mode) {
         return this.screenToDocumentPosition(screenRow, Number.MAX_VALUE / 10);
     };
 
-    /** internal, hide
-    * EditSession.getRowSplitData(row) -> undefined | String
-    *
+    /** 
+    * For the given row, this returns the split data.
+    * @returns {String}
     **/
     this.getRowSplitData = function(row) {
         if (!this.$useWrapMode) {
@@ -2097,41 +2121,34 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getScreenTabSize(screenColumn) -> Number
-    * - screenColumn (Number): The screen column to check
-    *
     * The distance to the next tab stop at the specified screen column.
+    * @param {Number} screenColumn The screen column to check
+    *
+    * 
+    * @returns {Number}
     **/
     this.getScreenTabSize = function(screenColumn) {
         return this.$tabSize - screenColumn % this.$tabSize;
     };
 
-    /** internal, hide
-    * EditSession.screenToDocumentRow(screenRow, screenColumn) -> Number
-    *
-    *
-    **/
+
     this.screenToDocumentRow = function(screenRow, screenColumn) {
         return this.screenToDocumentPosition(screenRow, screenColumn).row;
     };
 
-    /** internal, hide
-    * EditSession.screenToDocumentColumn(screenRow, screenColumn) -> Number
-    *
-    *
-    **/
+
     this.screenToDocumentColumn = function(screenRow, screenColumn) {
         return this.screenToDocumentPosition(screenRow, screenColumn).column;
     };
 
-    /** related to: EditSession.documentToScreenPosition
-    * EditSession.screenToDocumentPosition(screenRow, screenColumn) -> Object
-    * - screenRow (Number): The screen row to check
-    * - screenColumn (Number): The screen column to check
-    * + (Object): The object returned has two properties: `row` and `column`.
-    *
+    /** 
     * Converts characters coordinates on the screen to characters coordinates within the document. [This takes into account code folding, word wrap, tab size, and any other visual modifications.]{: #conversionConsiderations}
+    * @param {Number} screenRow The screen row to check
+    * @param {Number} screenColumn The screen column to check
+    * @returns {Object} The object returned has two properties: `row` and `column`.
+    *
     *
+    * @related EditSession.documentToScreenPosition
     *
     **/
     this.screenToDocumentPosition = function(screenRow, screenColumn) {
@@ -2147,14 +2164,12 @@ var EditSession = function(text, mode) {
 
         var rowCache = this.$screenRowCache;
         var i = this.$getRowCacheIndex(rowCache, screenRow);
-        var row1 = rowCache[i];
-        var docRow1 = this.$docRowCache[i];
         if (0 < i && i < rowCache.length) {
             var row = rowCache[i];
             var docRow = this.$docRowCache[i];
             var doCache = screenRow > row || (screenRow == row && i == rowCache.length - 1);
         } else {
-            var doCache = true;
+            var doCache = i != 0 || !rowCache.length;
         }
 
         var maxRow = this.getLength() - 1;
@@ -2218,15 +2233,14 @@ var EditSession = function(text, mode) {
         return {row: docRow, column: docColumn};
     };
 
-    /** related to: EditSession.screenToDocumentPosition
-    * EditSession.documentToScreenPosition(docRow, docColumn) -> Object
-    * - docRow (Number): The document row to check
-    * - docColumn (Number): The document column to check
-    * + (Object): The object returned by this method has two properties: `row` and `column`.
-    *
+    /** 
     * Converts document coordinates to screen coordinates. {:conversionConsiderations}
+    * @param {Number} docRow The document row to check
+    * @param {Number} docColumn The document column to check
+    * @returns {Object} The object returned by this method has two properties: `row` and `column`.
     *
     *
+    * @related EditSession.screenToDocumentPosition
     *
     **/
     this.documentToScreenPosition = function(docRow, docColumn) {
@@ -2260,7 +2274,7 @@ var EditSession = function(text, mode) {
             var screenRow = this.$screenRowCache[i];
             var doCache = docRow > row || (docRow == row && i == rowCache.length - 1);
         } else {
-            var doCache = true;
+            var doCache = i != 0 || !rowCache.length;
         }
 
         var foldLine = this.getNextFoldLine(row);
@@ -2316,8 +2330,10 @@ var EditSession = function(text, mode) {
         };
     };
 
-    /** internal, hide
-    * EditSession.documentToScreenColumn(row, docColumn) -> Number
+    /**
+    * For the given document row and column, returns the screen column.
+    * @param {Number} row
+    * @param {Number} docColumn
     *
     *
     **/
@@ -2325,8 +2341,10 @@ var EditSession = function(text, mode) {
         return this.documentToScreenPosition(row, docColumn).column;
     };
 
-    /** internal, hide
-    * EditSession.documentToScreenRow(docRow, docColumn) -> Number
+    /**
+    * For the given document row and column, returns the screen row.
+    * @param {Number} docRow
+    * @param {Number} docColumn
     *
     *
     **/
@@ -2335,9 +2353,8 @@ var EditSession = function(text, mode) {
     };
 
     /**
-    * EditSession.getScreenLength() -> Number
-    *
     * Returns the length of the screen.
+    * @returns {Number}
     **/
     this.getScreenLength = function() {
         var screenRows = 0;