fix: Fixed jsDoc annotations

Merge pull request #4879 from mkslanc/documentation-improvements

Author: andrewnester

src/ace.js

@@ -30,7 +30,7 @@ exports.config = require("./config");
 
 /**
  * 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
+ * @param {String | Element} el Either the id of an element, or the element itself
  * @param {Object } options Options for the editor
  *
  **/

src/anchor.js

@@ -36,7 +36,7 @@ var Anchor = exports.Anchor = function(doc, row, column) {
 
     /**
      * Returns an object identifying the `row` and `column` position of the current anchor.
-     * @returns {Object}
+     * @returns {Ace.Point}
      **/
     this.getPosition = function() {
         return this.$clipPositionToDocument(this.row, this.column);
@@ -68,6 +68,10 @@ var Anchor = exports.Anchor = function(doc, row, column) {
      *  - `value`: An object describing the new Anchor position
      *
      **/
+    /**
+     * Internal function called when `"change"` event fired.
+     * @param {Ace.Delta} delta
+     */
     this.onChange = function(delta) {
         if (delta.start.row == delta.end.row && delta.start.row != this.row)
             return;
@@ -158,6 +162,12 @@ var Anchor = exports.Anchor = function(doc, row, column) {
     this.detach = function() {
         this.document.off("change", this.$onChange);
     };
+
+    /**
+     * When called, the `"change"` event listener is appended.
+     * @param {Document} doc The document to associate with
+     *
+     **/
     this.attach = function(doc) {
         this.document = doc || this.document;
         this.document.on("change", this.$onChange);
@@ -167,6 +177,7 @@ var Anchor = exports.Anchor = function(doc, row, column) {
      * Clips the anchor position to the specified row and column.
      * @param {Number} row The row index to clip the anchor to
      * @param {Number} column The column index to clip the anchor to
+     * @returns {Ace.Point}
      *
      **/
     this.$clipPositionToDocument = function(row, column) {

src/autocomplete/popup.js

@@ -25,6 +25,16 @@ var $singleLineEditor = function(el) {
     return editor;
 };
 
+/**
+ * This object is used in some places where needed to show popups - like prompt; autocomplete etc.
+ * @class
+ */
+
+/**
+ * Creates and renders single line editor in popup window. If `parentNode` param is isset, then attaching it to this element.
+ * @param {Element} parentNode
+ * @constructor
+ */
 var AcePopup = function(parentNode) {
     var el = dom.createElement("div");
     var popup = new $singleLineEditor(el);

src/background_tokenizer.js

@@ -74,9 +74,7 @@ var BackgroundTokenizer = function(tokenizer, editor) {
 
     /**
      * Sets a new tokenizer for this object.
-     *
      * @param {Tokenizer} tokenizer The new tokenizer to use
-     *
      **/
     this.setTokenizer = function(tokenizer) {
         this.tokenizer = tokenizer;
@@ -109,7 +107,6 @@ var BackgroundTokenizer = function(tokenizer, editor) {
      * Emits the `'update'` event. `firstRow` and `lastRow` are used to define the boundaries of the region to be updated.
      * @param {Number} firstRow The starting row region
      * @param {Number} lastRow The final row region
-     *
      **/
     this.fireUpdateEvent = function(firstRow, lastRow) {
         var data = {
@@ -121,9 +118,7 @@ var BackgroundTokenizer = function(tokenizer, editor) {
 
     /**
      * Starts tokenizing at the row indicated.
-     *
      * @param {Number} startRow The row to start at
-     *
      **/
     this.start = function(startRow) {
         this.currentLine = Math.min(startRow || 0, this.currentLine, this.doc.getLength());
@@ -136,7 +131,10 @@ var BackgroundTokenizer = function(tokenizer, editor) {
         // pretty long delay to prevent the tokenizer from interfering with the user
         this.running = setTimeout(this.$worker, 700);
     };
-    
+
+    /**
+     * Sets pretty long delay to prevent the tokenizer from interfering with the user
+     */
     this.scheduleStart = function() {
         if (!this.running)
             this.running = setTimeout(this.$worker, 700);
@@ -165,7 +163,6 @@ var BackgroundTokenizer = function(tokenizer, editor) {
 
     /**
      * Stops tokenizing.
-     *
      **/
     this.stop = function() {
         if (this.running)
@@ -174,21 +171,18 @@ var BackgroundTokenizer = function(tokenizer, editor) {
     };
 
     /**
-     * Gives list of tokens of the row. (tokens are cached)
-     * 
+     * Gives list of [[Token]]'s of the row. (tokens are cached)
      * @param {Number} row The row to get tokens at
-     *
-     * 
-     *
+     * @returns {Token[]}
      **/
     this.getTokens = function(row) {
         return this.lines[row] || this.$tokenizeRow(row);
     };
 
     /**
-     * [Returns the state of tokenization at the end of a row.]{: #BackgroundTokenizer.getState}
-     *
+     * Returns the state of tokenization at the end of a row.
      * @param {Number} row The row to get state at
+     * @returns {string}
      **/
     this.getState = function(row) {
         if (this.currentLine == row)

src/bidihandler.js

@@ -226,9 +226,9 @@ var BidiHandler = function(session) {
 
     /**
      * Returns offset of character at position defined by column.
-     * @param {Number} the screen column position
+     * @param {Number} col the screen column position
      *
-     * @return {int} horizontal pixel offset of given screen column
+     * @return {Number} horizontal pixel offset of given screen column
      **/
     this.getPosLeft = function(col) {
         col -= this.wrapIndent;
@@ -258,10 +258,10 @@ var BidiHandler = function(session) {
 
     /**
      * Returns 'selections' - array of objects defining set of selection rectangles
-     * @param {Number} the start column position
-     * @param {Number} the end column position
+     * @param {Number} startCol the start column position
+     * @param {Number} endCol the end column position
      *
-     * @return {Array of Objects} Each object contains 'left' and 'width' values defining selection rectangle.
+     * @return {Object[]} Each object contains 'left' and 'width' values defining selection rectangle.
     **/
     this.getSelections = function(startCol, endCol) {
         var map = this.bidiMap, levels = map.bidiLevels, level, selections = [], offset = 0,
@@ -298,7 +298,7 @@ var BidiHandler = function(session) {
 
     /**
      * Converts character coordinates on the screen to respective document column number
-     * @param {int} character horizontal offset
+     * @param {Number} posX character horizontal offset
      *
      * @return {Number} screen column number corresponding to given pixel offset
     **/

src/document.js

@@ -16,7 +16,7 @@ var Anchor = require("./anchor").Anchor;
 /**
  *
  * Creates a new `Document`. If `text` is included, the `Document` contains those strings; otherwise, it's empty.
- * @param {String | Array} text The starting text
+ * @param {String | String[]} textOrLines text The starting text
  * @constructor
  **/
 
@@ -190,7 +190,7 @@ var Document = function(textOrLines) {
      * Returns all the text within `range` as an array of lines.
      * @param {Range} range The range to work with.
      * 
-     * @returns {Array}
+     * @returns {string[]}
      **/
     this.getLinesForRange = function(range) {
         var lines;
@@ -322,7 +322,7 @@ var Document = function(textOrLines) {
     /**
      * Inserts the elements in `lines` into the document as full lines (does not merge with existing line), starting at the row index given by `row`. This method also triggers the `"change"` event.
      * @param {Number} row The index of the row to insert at
-     * @param {Array} lines An array of strings
+     * @param {string[]} lines An array of strings
      * @returns {Object} Contains the final row and column, like this:  
      *   ```
      *   {row: endRow, column: 0}
@@ -358,7 +358,7 @@ var Document = function(textOrLines) {
     /**
      * Inserts the elements in `lines` into the document, starting at the position index given by `row`. This method also triggers the `"change"` event.
      * @param {Number} row The index of the row to insert at
-     * @param {Array} lines An array of strings
+     * @param {string[]} lines An array of strings
      * @returns {Object} Contains the final row and column, like this:  
      *   ```
      *   {row: endRow, column: 0}
@@ -514,7 +514,7 @@ var Document = function(textOrLines) {
 
     /**
      * Applies all changes in `deltas` to the document.
-     * @param {Array} deltas An array of delta objects (can include "insert" and "remove" actions)
+     * @param {Delta[]} deltas An array of delta objects (can include "insert" and "remove" actions)
      **/
     this.applyDeltas = function(deltas) {
         for (var i=0; i<deltas.length; i++) {
@@ -524,7 +524,7 @@ var Document = function(textOrLines) {
 
     /**
      * Reverts all changes in `deltas` from the document.
-     * @param {Array} deltas An array of delta objects (can include "insert" and "remove" actions)
+     * @param {Delta[]} deltas An array of delta objects (can include "insert" and "remove" actions)
      **/
     this.revertDeltas = function(deltas) {
         for (var i=deltas.length-1; i>=0; i--) {

src/edit_session.js

@@ -102,9 +102,9 @@ var SearchHighlight = require("./search_highlight").SearchHighlight;
 //}
 
 /**
- * Sets up a new `EditSession` and associates it with the given `Document` and `TextMode`.
+ * Sets up a new `EditSession` and associates it with the given `Document` and `Mode`.
  * @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]{: #textParam}
- * @param {TextMode} mode [The initial language mode to use for the document]{: #modeParam}
+ * @param {Mode} mode [The initial language mode to use for the document]{: #modeParam}
  *
  * @constructor
  **/
@@ -683,7 +683,7 @@ EditSession.$uid = 0;
      */
     /**
      * Sets annotations for the `EditSession`. This functions emits the `'changeAnnotation'` event.
-     * @param {Array} annotations A list of annotations
+     * @param {Annotation[]} annotations A list of annotations
      *
      **/
     this.setAnnotations = function(annotations) {
@@ -693,7 +693,7 @@ EditSession.$uid = 0;
 
     /**
      * Returns the annotations for the `EditSession`.
-     * @returns {Array}
+     * @returns {Annotation[]}
      **/
     this.getAnnotations = function() {
         return this.$annotations || [];
@@ -1113,7 +1113,7 @@ EditSession.$uid = 0;
 
     /**
      * Reverts previous changes to your document.
-     * @param {Array} deltas An array of previous changes
+     * @param {Delta[]} deltas An array of previous changes
      * @param {Boolean} dontSelect [If `true`, doesn't select the range of where the change occured]{: #dontSelect}
      *
      * @returns {Range}
@@ -1142,7 +1142,7 @@ EditSession.$uid = 0;
 
     /**
      * Re-implements a previously undone change to your document.
-     * @param {Array} deltas An array of previous changes
+     * @param {Delta[]} deltas An array of previous changes
      * @param {Boolean} dontSelect {:dontSelect}
      *
      * @returns {Range}
@@ -2077,7 +2077,7 @@ EditSession.$uid = 0;
      * 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
-     * @param {int} screen character x-offset [optional]
+     * @param {Number} offsetX screen character x-offset [optional]
      *
      * @returns {Object} The object returned has two properties: `row` and `column`.
      *

src/ext/menu_tools/overlay_page.js

@@ -22,7 +22,7 @@ dom.importCssString(cssText, "settings_menu.css", false);
  * @author <a href="mailto:matthewkastor@gmail.com">
  *  Matthew Christopher Kastor-Inare III </a><br />
  *  ☭ Hial Atropa!! ☭
- * @param {DOMElement} contentElement Any element which may be presented inside
+ * @param {Element} contentElement Any element which may be presented inside
  *  a div.
  */
 

src/keyboard/vim.js

@@ -4503,7 +4503,7 @@ dom.importCssString(".normal-mode .ace_cursor{\
     /**
      * @param {CodeMirror} cm CodeMirror object.
      * @param {Pos} cur The position to start from.
-     * @param {int} repeat Number of words to move past.
+     * @param {Number} repeat Number of words to move past.
      * @param {boolean} forward True to search forward. False to search
      *     backward.
      * @param {boolean} wordEnd True to move to end of word. False to move to

src/lib/bidiutil.js

@@ -364,10 +364,10 @@ exports.hasBidiCharacters = function(text, textCharTypes){
 /**
  * Returns visual index corresponding to logical index basing on logicalFromvisual 
  * map provided by Unicode Bidi algorithm.
- * @param {int} logical index of character in text buffer
- * @param {Object} object containing logicalFromVisual map
+ * @param {Number} logIdx logical index of character in text buffer
+ * @param {Object} rowMap object containing logicalFromVisual map
  *
- * @return {int} visual index (on display) corresponding to logical index
+ * @return {Number} visual index (on display) corresponding to logical index
  **/	
 exports.getVisualFromLogicalIdx = function(logIdx, rowMap) {
 	for (var i = 0; i < rowMap.logicalFromVisual.length; i++) {

src/mode/folding/sqlserver.js

@@ -47,7 +47,7 @@ oop.inherits(FoldMode, BaseFoldMode);
     };
 
     /**
-     * @returns {range} folding block for sequence that starts with 'CASE' or 'BEGIN' and ends with 'END'
+     * @returns {Range} folding block for sequence that starts with 'CASE' or 'BEGIN' and ends with 'END'
      * @param {string} matchSequence - the sequence of charaters that started the fold widget, which should remain visible when the fold widget is folded
      */
     this.getBeginEndBlock = function(session, row, column, matchSequence) {

src/multi_select.js

@@ -157,7 +157,7 @@ var EditSession = require("./edit_session").EditSession;
 
     /**
      * Returns a concatenation of all the ranges.
-     * @returns {Array}
+     * @returns {Range[]}
      * @method Selection.getAllRanges
      **/
     this.getAllRanges = function() {