background_tokenizer.js in gollum-2.4.5

- old
+ new

@@ -1,40 +1,33 @@
 /* ***** 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/
+ * 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.
  *
- * 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>
- *
- * 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.
- *
  * ***** END LICENSE BLOCK ***** */
 
 define(function(require, exports, module) {
 "use strict";
 
@@ -43,24 +36,27 @@
 
 // tokenizing lines longer than this makes editor very slow
 var MAX_LINE_LENGTH = 5000;
 
 /**
- * class BackgroundTokenizer
+ * 
  *
- * Tokenizes the current [[Document `Document`]] in the background, and caches the tokenized rows for future use. If a certain row is changed, everything below that row is re-tokenized.
+ * Tokenizes the current [[Document `Document`]] in the background, and caches the tokenized rows for future use. 
+ * 
+ * If a certain row is changed, everything below that row is re-tokenized.
  *
+ * @class BackgroundTokenizer
  **/
 
 /**
- * new BackgroundTokenizer(tokenizer, editor)
- * - tokenizer (Tokenizer): The tokenizer to use
- * - editor (Editor): The editor to associate with
- *
  * Creates a new `BackgroundTokenizer` object.
+ * @param {Tokenizer} tokenizer The tokenizer to use
+ * @param {Editor} editor The editor to associate with
  *
- *
+ * 
+ * 
+ * @constructor
  **/
 
 var BackgroundTokenizer = function(tokenizer, editor) {
     this.running = false;
     this.lines = [];
@@ -103,45 +99,46 @@
 (function(){
 
     oop.implement(this, EventEmitter);
 
     /**
-     * BackgroundTokenizer.setTokenizer(tokenizer)
-     * - tokenizer (Tokenizer): The new tokenizer to use
-     *
      * Sets a new tokenizer for this object.
      *
+     * @param {Tokenizer} tokenizer The new tokenizer to use
+     *
      **/
     this.setTokenizer = function(tokenizer) {
         this.tokenizer = tokenizer;
         this.lines = [];
         this.states = [];
 
         this.start(0);
     };
 
     /**
-     * BackgroundTokenizer.setDocument(doc)
-     * - doc (Document): The new document to associate with
-     *
      * Sets a new document to associate with this object.
-     *
+     * @param {Document} doc The new document to associate with
      **/
     this.setDocument = function(doc) {
         this.doc = doc;
         this.lines = [];
         this.states = [];
 
         this.stop();
     };
 
-    /**
-     * BackgroundTokenizer.fireUpdateEvent(firstRow, lastRow)
-     * - firstRow (Number): The starting row region
-     * - lastRow (Number): The final row region
+     /**
+     * Fires whenever the background tokeniziers between a range of rows are going to be updated.
+     * 
+     * @event update
+     * @param {Object} e An object containing two properties, `first` and `last`, which indicate the rows of the region being updated.
      *
+     **/
+    /**
      * 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 = {
             first: firstRow,
@@ -149,15 +146,14 @@
         };
         this._emit("update", {data: data});
     };
 
     /**
-     * BackgroundTokenizer.start(startRow)
-     * - startRow (Number): The row to start at
-     *
      * 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());
 
         // remove all cached items below this line
@@ -192,37 +188,34 @@
         // pretty long delay to prevent the tokenizer from interfering with the user
         this.running = setTimeout(this.$worker, 700);
     };
 
     /**
-     * BackgroundTokenizer.stop()
-     *
      * Stops tokenizing.
      *
      **/
     this.stop = function() {
         if (this.running)
             clearTimeout(this.running);
         this.running = false;
     };
 
-    /** related to: BackgroundTokenizer.$tokenizeRows
-     * BackgroundTokenizer.getTokens(firstRow, lastRow) -> [Object]
-     * - firstRow (Number): The row to start at
-     * - lastRow (Number): The row to finish at
+    /**
+     * Gives list of tokens of the row. (tokens are cached)
+     * 
+     * @param {Number} row The row to get tokens at
      *
-     * Starts tokenizing at the row indicated. Returns a list of objects of the tokenized rows.
+     * 
      *
      **/
     this.getTokens = function(row) {
         return this.lines[row] || this.$tokenizeRow(row);
     };
 
     /**
-     * BackgroundTokenizer.getState(row) -> String
-     * - row (Number): The row to start at
-     *
      * [Returns the state of tokenization at the end of a row.]{: #BackgroundTokenizer.getState}
+     *
+     * @param {Number} row The row to get state at
      **/
     this.getState = function(row) {
         if (this.currentLine == row)
             this.$tokenizeRow(row);
         return this.states[row] || "start";