Update docs to use undocumented, also incorporate Site branch changes

lib/ace/ace.js

@@ -56,11 +56,10 @@ require("./mode/folding/fold_mode");
 exports.config = require("./config");
 
 /**
+ * Provides access to require in packed noconflict mode
  * @param {String} moduleName
  * @returns {Object}
  *
- * provides access to require in packed noconflict mode
- *
  **/
 exports.require = require;
 
@@ -68,8 +67,6 @@ exports.require = require;
  * Embeds the Ace editor into the DOM, at the element provided by `el`.
  * @param {String | DOMElement} el Either the id of an element, or the element itself
  *
- * This method embeds the Ace editor into the DOM, at the element provided by `el`.
- *
  **/
 exports.edit = function(el) {
     if (typeof(el) == "string") {

lib/ace/editor.js

@@ -1050,8 +1050,6 @@ var Editor = function(renderer, session) {
     };
 
     /**
-     * Editor.getWrapBehavioursEnabled() -> Boolean
-     * 
      * Returns `true` if the wrapping behaviors are currently enabled.
      **/
     this.getWrapBehavioursEnabled = function () {

lib/ace/multi_select.js

@@ -66,12 +66,11 @@ var EditSession = require("./edit_session").EditSession;
     // automatically sorted list of ranges
     this.rangeList = null;
 
-    /** extension
-     * Selection.addRange(range, $blockChangeEvents)
-     * - range (Range): The new range to add
-     * - $blockChangeEvents (Boolean): Whether or not to block changing events
-     *
+    /** 
      * Adds a range to a selection by entering multiselect mode, if necessary.
+     * @param {Range} range The new range to add
+     * @param {Boolean} $blockChangeEvents Whether or not to block changing events
+     * @method Selection.addRange
      **/
     this.addRange = function(range, $blockChangeEvents) {
         if (!range)
@@ -106,6 +105,10 @@ var EditSession = require("./edit_session").EditSession;
         return $blockChangeEvents || this.fromOrientedRange(range);
     };
 
+    /**
+     * @method Selection.toSingleRange
+     **/
+
     this.toSingleRange = function(range) {
         range = range || this.ranges[0];
         var removed = this.rangeList.removeAll();
@@ -115,11 +118,10 @@ var EditSession = require("./edit_session").EditSession;
         range && this.fromOrientedRange(range);
     };
 
-    /** extension
-     * Selection.substractPoint(pos) -> Range
-     * - pos (Range): The position to remove, as a `{row, column}` object
-     *
+    /**
      * Removes a Range containing pos (if it exists).
+     * @param {Range} pos The position to remove, as a `{row, column}` object
+     * @method Selection.substractPoint
      **/
     this.substractPoint = function(pos) {
         var removed = this.rangeList.substractPoint(pos);
@@ -129,10 +131,9 @@ var EditSession = require("./edit_session").EditSession;
         }
     };
 
-    /** extension
-     * Selection.mergeOverlappingRanges()
-     *
+    /**
      * Merges overlapping ranges ensuring consistency after changes
+     * @method Selection.mergeOverlappingRanges
      **/
     this.mergeOverlappingRanges = function() {
         var removed = this.rangeList.merge();
@@ -185,10 +186,20 @@ var EditSession = require("./edit_session").EditSession;
         this.rangeCount = 0;
     };
 
+    /**
+     * Returns a concatenation of all the ranges.
+     * @returns Array
+     * @method Selection.getAllRanges
+     **/
     this.getAllRanges = function() {
         return this.rangeList.ranges.concat();
     };
 
+    /**
+     * Splits all the ranges into lines.
+     * @method Selection.splitIntoLines
+     **/
+
     this.splitIntoLines = function () {
         if (this.rangeCount > 1) {
             var ranges = this.rangeList.ranges;
@@ -229,6 +240,9 @@ var EditSession = require("./edit_session").EditSession;
         }
     };
 
+    /**
+     * @method Selection.toggleBlockSelection
+     **/
     this.toggleBlockSelection = function () {
         if (this.rangeCount > 1) {
             var ranges = this.rangeList.ranges;
@@ -246,14 +260,15 @@ var EditSession = require("./edit_session").EditSession;
         }
     };
 
-    /** extension
-     * Selection.rectangularRangeBlock(screenCursor, screenAnchor, includeEmptyLines) -> Range
-     * - screenCursor (Cursor): The cursor to use
-     * - screenAnchor (Anchor): The anchor to use
-     * - includeEmptyLines (Boolean): If true, this includes ranges inside the block which are empty due to clipping
-     *
+    /**
+     * 
      * Gets list of ranges composing rectangular block on the screen
-     *
+     * 
+     * @param {Cursor} screenCursor The cursor to use
+     * @param {Anchor} screenAnchor The anchor to use
+     * @param {Boolean} includeEmptyLines If true, this includes ranges inside the block which are empty due to clipping
+     * @returns Range
+     * @method Selection.rectangularRangeBlock
      **/
     this.rectangularRangeBlock = function(screenCursor, screenAnchor, includeEmptyLines) {
         var rectSel = [];
@@ -325,9 +340,10 @@ var Editor = require("./editor").Editor;
 (function() {
 
     /** 
-     * Editor.updateSelectionMarkers()
-     *
+     * 
      * Updates the cursor and marker layers.
+     * @method Editor.updateSelectionMarkers
+     *
      **/
     this.updateSelectionMarkers = function() {
         this.renderer.updateCursor();
@@ -335,10 +351,10 @@ var Editor = require("./editor").Editor;
     };
 
     /** 
-     * Editor.addSelectionMarker(orientedRange) -> Range
-     * - orientedRange (Range): A range containing a cursor
-     *
      * Adds the selection and cursor.
+     * @param {Range} orientedRange A range containing a cursor
+     * @returns Range
+     * @method Editor.addSelectionMarker
      **/
     this.addSelectionMarker = function(orientedRange) {
         if (!orientedRange.cursor)
@@ -353,10 +369,9 @@ var Editor = require("./editor").Editor;
     };
 
     /** 
-     * Editor.removeSelectionMarker(range)
-     * - range (Range): The selection range added with [[Editor.addSelectionMarker `addSelectionMarker()`]].
-     *
      * Removes the selection marker.
+     * @param {Range} The selection range added with [[Editor.addSelectionMarker `addSelectionMarker()`]].
+     * @method Editor.removeSelectionMarker
      **/
     this.removeSelectionMarker = function(range) {
         if (!range.marker)
@@ -441,12 +456,11 @@ var Editor = require("./editor").Editor;
     };
 
     /** 
-     * Editor.forEachSelection(cmd, args)
-     * - cmd (String): The command to execute
-     * - args (String): Any arguments for the command
-     *
      * Executes a command for each selection range.
-     **/
+     * @param {String} cmd The command to execute
+     * @param {String} args Any arguments for the command
+     * @method Editor.forEachSelection
+     **/ 
     this.forEachSelection = function(cmd, args) {
         if (this.inVirtualSelectionMode)
             return;
@@ -478,9 +492,8 @@ var Editor = require("./editor").Editor;
     };
 
     /** 
-    * Editor.exitMultiSelectMode() -> Void
-    *
     * Removes all the selections except the last added one.
+    * @method Editor.exitMultiSelectMode
     **/
     this.exitMultiSelectMode = function() {
         if (this.inVirtualSelectionMode)
@@ -529,12 +542,12 @@ var Editor = require("./editor").Editor;
     };
 
     /**
-     * Editor.findAll(needle, options, additive) -> Number
-     * - needle (String): The text to find
-     * - options (Object): The search options
-     * - additive (Boolean): keeps
-     *
      * Finds and selects all the occurences of `needle`.
+     * @param {String} The text to find
+     * @param {Object} The search options
+     * @param {Boolean} keeps
+     * @returns Number
+     * @method Editor.findAll
      **/
     this.findAll = function(needle, options, additive) {
         options = options || {};
@@ -605,11 +618,10 @@ var Editor = require("./editor").Editor;
             this.selection.substractPoint(toRemove);
     };
 
-    /** extension
-     * Editor.transposeSelections(dir)
-     * - dir (Number): The direction to rotate selections
-     *
+    /** 
      * Transposes the selected ranges.
+     * @param dir {Number} The direction to rotate selections
+     * @method Editor.transposeSelections
      **/
     this.transposeSelections = function(dir) {
         var session = this.session;
@@ -648,12 +660,11 @@ var Editor = require("./editor").Editor;
         }
     };
 
-    /** extension
-     * Editor.selectMore(dir, skip)
-     * - dir (Number): The direction of lines to select: -1 for up, 1 for down
-     * - skip (Boolean): If `true`, removes the active selection range
-     *
+    /** 
      * Finds the next occurence of text in an active selection and adds it to the selections.
+     * @param {Number} dir The direction of lines to select: -1 for up, 1 for down
+     * @param {Boolean} skip If `true`, removes the active selection range
+     * @method Editor.selectMore
      **/
     this.selectMore = function(dir, skip) {
         var session = this.session;
@@ -676,10 +687,9 @@ var Editor = require("./editor").Editor;
             this.multiSelect.substractPoint(range.cursor);
     };
 
-    /** extension
-     * Editor.alignCursors()
-     *
-     * aligns cursors or selected text
+    /** 
+     * Aligns the cursors or selected text.
+     * @method Editor.alignCursors
      **/
     this.alignCursors = function() {
         var session = this.session;

lib/ace/split.js

@@ -299,9 +299,6 @@ var Split = function(container, theme, splits) {
     };
 
    /**  
-     * Split.resize() -> Void
-     *
-     *
      * Resizes the editor.
      **/
     this.resize = function() {