jyapayne/ace
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Make some updates to doc

Browse source
This commit is contained in:
Garen Torikian 2012-02-07 16:22:22 -08:00
commit 554b845bb9
12 changed files with 219 additions and 157 deletions
Download patch file Download diff file Expand all files Collapse all files

4
doc/resources/ace/skins/skeleton/images/Ace_ERD.svg Normal file
View file

File diff suppressed because one or more lines are too long
Side by side

After

Width:  |  Height:  |  Size: 296 KiB

6
lib/ace/ace.js
View file

@ -38,7 +38,7 @@
/** /**
* class Ace * class Ace
* *
* TODO * The main class required to set up an Ace instance in the browser.
* *
* *
**/ **/
@ -58,9 +58,9 @@ var Renderer = require("./virtual_renderer").VirtualRenderer;
/** /**
* Ace.edit(el) -> Editor * Ace.edit(el) -> Editor
* - el (String | Element): Either the id of an element to edit, or the element itself * - el (String | Element): Either the id of an element, or the element itself
* *
* Edits an element. TODO. * This method embeds the Ace editor into the DOM, at the element provided by `el`.
* *
**/ **/
exports.edit = function(el) { exports.edit = function(el) {

8
lib/ace/anchor.js
View file

@ -98,9 +98,9 @@ var Anchor = exports.Anchor = function(doc, row, column) {
/** /**
* Anchor@onChange(e) * Anchor@onChange(e)
* - e (Event): TODO * - e (Event): Contains data about the event
* *
* Fires whenever the anchor position changes. * Fires whenever the anchor position changes. Events that can trigger this function include `'includeText'`, `'insertLines'`, `'removeText'`, and `'removeLines'`.
* *
**/ **/
@ -218,12 +218,12 @@ var Anchor = exports.Anchor = function(doc, row, column) {
this.document.removeEventListener("change", this.$onChange); this.document.removeEventListener("change", this.$onChange);
}; };
/** /** internal
* Anchor.clipPositionToDocument(row, column) -> Void * Anchor.clipPositionToDocument(row, column) -> Void
* - row (Number): The row index to clip the anchor to * - row (Number): The row index to clip the anchor to
* - column (Number): The column index to clip the anchor to * - column (Number): The column index to clip the anchor to
* *
* Clips the anchor position to the specified row and column. TODO * Clips the anchor position to the specified row and column.
* *
**/ **/

8
lib/ace/background_tokenizer.js
View file

@ -44,7 +44,7 @@ var EventEmitter = require("./lib/event_emitter").EventEmitter;
/** /**
* class BackgroundTokenizer * class BackgroundTokenizer
* *
* Tokenizes items..in the background? TODO * Tokenizes items...in the background? TODO
* *
* *
**/ **/
@ -194,11 +194,11 @@ var BackgroundTokenizer = function(tokenizer, editor) {
return this.$tokenizeRows(firstRow, lastRow); return this.$tokenizeRows(firstRow, lastRow);
}; };
/** related to: BackgroundTokenizer.$tokenizeRows /**
* BackgroundTokenizer.getState(row) -> Array * BackgroundTokenizer.getState(row) -> String
* - row (Number): The row to start at * - row (Number): The row to start at
* *
* Retrieves the state of tokenization for a row. Returns the tokenized row. * [Returns the state of tokenization for a row.](~BackgroundTokenizer.getState)
* *
**/ **/

55
lib/ace/document.js
View file

@ -46,16 +46,16 @@ var Anchor = require("./anchor").Anchor;
/** /**
* class Document * class Document
* *
* Documentation about Document. Is this recursion? TODO * Contains the text of the document. Documents are controlled by a single [[EditSession `EditSession`]]. At its core, `Document`s are just an array of strings, with each row in the document matching up to the array index.
* *
* *
**/ **/
/** /**
* new Document(text) * new Document([text])
* - text (String | Array): The starting text * - text (String | Array): The starting text
* *
* Creates a new `Document`. TODO * Creates a new `Document`. If `text` is included, the `Document` contains those strings; otherwise, it's empty.
* *
**/ **/
var Document = function(text) { var Document = function(text) {
@ -77,11 +77,11 @@ var Document = function(text) {
oop.implement(this, EventEmitter); oop.implement(this, EventEmitter);
/** /**
* Document.setValue(text) -> Void * Document.setValue(text) -> Void
* - text (String): The value to set * - text (String): The text to use
* *
* * Replaces all the lines in the current `Document` with the value of `text`.
**/ **/
this.setValue = function(text) { this.setValue = function(text) {
var len = this.getLength(); var len = this.getLength();
@ -89,25 +89,27 @@ var Document = function(text) {
this.insert({row: 0, column:0}, text); this.insert({row: 0, column:0}, text);
}; };
/** /**
* Document.getValue() -> String * Document.getValue() -> String
* *
* Returns all the lines in the document, split by the new line character. * Returns all the lines in the document as a single string, split by the new line character.
**/ **/
this.getValue = function() { this.getValue = function() {
return this.getAllLines().join(this.getNewLineCharacter()); return this.getAllLines().join(this.getNewLineCharacter());
}; };
/** /**
* Document.createAnchor(row, column) -> Anchor * Document.createAnchor(row, column) -> Anchor
* * - row (Number): The row number to use
* * - column (Number): The column number to use
*
* Creates a new `Anchor` to define a floating point in the document.
**/ **/
this.createAnchor = function(row, column) { this.createAnchor = function(row, column) {
return new Anchor(this, row, column); return new Anchor(this, row, column);
}; };
/** /** internal
* Document.$split(text) -> Array * Document.$split(text) -> Array
* - text (String): The text to work with * - text (String): The text to work with
* *
@ -130,7 +132,7 @@ var Document = function(text) {
}; };
/** /** internal
* Document.$detectNewLine(text) -> Void * Document.$detectNewLine(text) -> Void
* *
* *
@ -147,7 +149,7 @@ var Document = function(text) {
/** /**
* Document.getNewLineCharacter() -> String * Document.getNewLineCharacter() -> String
* *
* Returns the new line character that's being used, depending on the value of `newLineMode`. * Returns the newline character that's being used, depending on the value of `newLineMode`.
* *
* #### Returns * #### Returns
* *
@ -174,9 +176,9 @@ var Document = function(text) {
this.$newLineMode = "auto"; this.$newLineMode = "auto";
/** /**
* Document.setNewLineMode(newLineMode) -> Void * Document.setNewLineMode(newLineMode) -> Void
* - newLineMode(String): The newline mode to use; can be either `windows`, `unix`, or `auto` * - newLineMode(String): [The newline mode to use; can be either `windows`, `unix`, or `auto`](~Document.setNewLineMode.param)
* *
* Sets the new line mode. * [Sets the new line mode.](~Document.setNewLineMode.desc)
**/ **/
this.setNewLineMode = function(newLineMode) { this.setNewLineMode = function(newLineMode) {
if (this.$newLineMode === newLineMode) if (this.$newLineMode === newLineMode)
@ -188,7 +190,7 @@ var Document = function(text) {
/** /**
* Document.getNewLineMode() -> String * Document.getNewLineMode() -> String
* *
* Returns the type of newlines being used; either `windows`, `unix`, or `auto` * [Returns the type of newlines being used; either `windows`, `unix`, or `auto`](~Document.getNewLineMode)
* *
**/ **/
this.getNewLineMode = function() { this.getNewLineMode = function() {
@ -248,10 +250,10 @@ var Document = function(text) {
}; };
/** /**
* Document.getTextRange(range) -> Array * Document.getTextRange(range) -> String
* - range (String): blah * - range (Range): The range to work with
* *
* TODO * [Given a range within the document, this function returns all the text within that range as a single string.](~Document.getTextRange.desc)
**/ **/
this.getTextRange = function(range) { this.getTextRange = function(range) {
if (range.start.row == range.end.row) { if (range.start.row == range.end.row) {
@ -267,11 +269,10 @@ var Document = function(text) {
} }
}; };
/** /** internal
* Document.$clipPosition(position) -> Number * Document.$clipPosition(position) -> Number
* - position (Number): blah
* *
* TODO *
**/ **/
this.$clipPosition = function(position) { this.$clipPosition = function(position) {
var length = this.getLength(); var length = this.getLength();
@ -529,9 +530,9 @@ var Document = function(text) {
/** /**
* Document.removeNewLine(row) -> Void * Document.removeNewLine(row) -> Void
* - row (Number): The row to be removed * - row (Number): The row to check
* *
* TODO Removes the row from the document. This method also triggers the `'change'` event. * Removes the new line between `row` and the row immediately following it. This method also triggers the `'change'` event.
* *
**/ **/
this.removeNewLine = function(row) { this.removeNewLine = function(row) {
@ -592,7 +593,7 @@ var Document = function(text) {
/** /**
* Document.applyDeltas(deltas) -> Void * Document.applyDeltas(deltas) -> Void
* *
* TODO * Applies all the changes previously accumulated. These can be either `'includeText'`, `'insertLines'`, `'removeText'`, and `'removeLines'`.
**/ **/
this.applyDeltas = function(deltas) { this.applyDeltas = function(deltas) {
for (var i=0; i<deltas.length; i++) { for (var i=0; i<deltas.length; i++) {
@ -613,7 +614,7 @@ var Document = function(text) {
/** /**
* Document.revertDeltas(deltas) -> Void * Document.revertDeltas(deltas) -> Void
* *
* TODO * Reverts any changes previously applied. These can be either `'includeText'`, `'insertLines'`, `'removeText'`, and `'removeLines'`.
**/ **/
this.revertDeltas = function(deltas) { this.revertDeltas = function(deltas) {
for (var i=deltas.length-1; i>=0; i--) { for (var i=deltas.length-1; i>=0; i--) {

192
lib/ace/edit_session.js
View file

@ -53,16 +53,16 @@ var BackgroundTokenizer = require("./background_tokenizer").BackgroundTokenizer;
/** /**
* class EditSession * class EditSession
* *
* Some sessions stuff. * Stores various states related to a [[Document `Document`]]. A single `EditSession` can be in charge of several `Document`s.
* *
**/ **/
/** /**
* new EditSession(text, mode) * new EditSession(text, mode)
* - text (String): Some text * - 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 (Boolean): A boolean * - mode (TextMode): The inital language mode to use for the document
* *
* TODO * Sets up a new `EditSession` and associates it with the given `Document` and `TextMode`.
* *
**/ **/
@ -104,9 +104,9 @@ var EditSession = function(text, mode) {
/** /**
* EditSession.setDocument(doc) -> Void * EditSession.setDocument(doc) -> Void
* - doc (Document): Some text * - doc (Document): The new `Document` to use
* *
* TODO Does some stuff. * Sets the `EditSession` to point to a new `Document`. If a `BackgroundTokenizer` exists, it also points to `doc`.
* *
**/ **/
this.setDocument = function(doc) { this.setDocument = function(doc) {
@ -133,11 +133,11 @@ var EditSession = function(text, mode) {
return this.doc; return this.doc;
}; };
/** /** internal
* EditSession.$resetRowCache(row) -> Void * EditSession.$resetRowCache(row) -> Void
* - row (Number): The row to work with * - row (Number): The row to work with
* *
* TODO Does some stuff. *
* *
**/ **/
this.$resetRowCache = function(row) { this.$resetRowCache = function(row) {
@ -155,10 +155,9 @@ var EditSession = function(text, mode) {
}; };
/** /**
* EditSession@onChangeFold(e) * EditSession@onChangeFold(e) -> Void
* *
* * Emitted when a code fold changes its state.
* This event triggers when code folds change their state. TODO
* *
**/ **/
this.onChangeFold = function(e) { this.onChangeFold = function(e) {
@ -167,9 +166,9 @@ var EditSession = function(text, mode) {
}; };
/** /**
* EditSession@onChange(e) * EditSession@onChange(e) -> Void
* *
* This changes TODO * Emitted when the document changes.
**/ **/
this.onChange = function(e) { this.onChange = function(e) {
var delta = e.data; var delta = e.data;
@ -213,13 +212,19 @@ var EditSession = function(text, mode) {
this.getUndoManager().reset(); this.getUndoManager().reset();
}; };
this.getValue = /** alias of: EditSession.toString()
/** * EditSession.getValue() -> String
* EditSession.toString() -> String *
* * Returns the current [[Document `Document`]] as a string.
* Returns the current [[Document `Document`]] as a string.
* *
**/ **/
/** alias of: EditSession.getValue()
* EditSession.toString() -> String
*
* Returns the current [[Document `Document`]] as a string.
*
**/
this.getValue =
this.toString = function() { this.toString = function() {
return this.doc.getValue(); return this.doc.getValue();
}; };
@ -237,7 +242,7 @@ var EditSession = function(text, mode) {
* EditSession.getState(row) -> Array * EditSession.getState(row) -> Array
* - row (Number): The row to start at * - row (Number): The row to start at
* *
* Retrieves the state of tokenization for a row. Returns the tokenized row. TODO * (~BackgroundTokenizer.getState)
* *
**/ **/
this.getState = function(row) { this.getState = function(row) {
@ -302,10 +307,10 @@ var EditSession = function(text, mode) {
if (undoManager) { if (undoManager) {
var self = this; var self = this;
/** /** internal
* EditSession.$syncInformUndoManager() -> Void * EditSession.$syncInformUndoManager() -> Void
* *
* TODO *
**/ **/
this.$syncInformUndoManager = function() { this.$syncInformUndoManager = function() {
self.$informUndoManager.cancel(); self.$informUndoManager.cancel();
@ -418,9 +423,9 @@ var EditSession = function(text, mode) {
/** /**
* EditSession.isTabStop(position) -> Boolean * EditSession.isTabStop(position) -> Boolean
* - position (Number): The position to check * - position (Object): The position to check
* *
* Returns `true` if the character at the position is a soft tab. TODO * Returns `true` if the character at the position is a soft tab.
**/ **/
this.isTabStop = function(position) { this.isTabStop = function(position) {
return this.$useSoftTabs && (position.column % this.$tabSize == 0); return this.$useSoftTabs && (position.column % this.$tabSize == 0);
@ -516,13 +521,14 @@ var EditSession = function(text, mode) {
}; };
/** /**
* EditSession.addMarker(range, clazz, type, inFront) -> Number * EditSession.addMarker(range, clazz, type = "line", inFront) -> Number
* - range (Range): * - range (Range): Define the range of the marker
* - clazz (String): * - clazz (String): Set the CSS class for the marker
* - type (String): * - type (Function || String): Identify the type of the marker
* - inFront (Boolean): * - 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.
* *
* TODO
**/ **/
this.addMarker = function(range, clazz, type, inFront) { this.addMarker = function(range, clazz, type, inFront) {
var id = this.$markerId++; var id = this.$markerId++;
@ -587,9 +593,9 @@ var EditSession = function(text, mode) {
*/ */
/** /**
* EditSession.setAnnotations(annotations) -> Void * EditSession.setAnnotations(annotations) -> Void
* - annotations (Array): * - annotations (Array): A list of annotations
* *
* This functions emits the `'changeAnnotation'` event. TODO * Sets annotations for the `EditSession`. This functions emits the `'changeAnnotation'` event.
**/ **/
this.setAnnotations = function(annotations) { this.setAnnotations = function(annotations) {
this.$annotations = {}; this.$annotations = {};
@ -605,9 +611,9 @@ var EditSession = function(text, mode) {
}; };
/** /**
* EditSession.getAnnotations() -> Array * EditSession.getAnnotations() -> Object
* *
* TODO * Returns the annotations for the `EditSession`.
**/ **/
this.getAnnotations = function() { this.getAnnotations = function() {
return this.$annotations || {}; return this.$annotations || {};
@ -623,11 +629,11 @@ var EditSession = function(text, mode) {
this._emit("changeAnnotation", {}); this._emit("changeAnnotation", {});
}; };
/** /** internal
* EditSession.$detectNewLine(text) -> Void * EditSession.$detectNewLine(text) -> Void
* - text (String): A block of text * - text (String): A block of text
* *
* If `text` contains either the newline (`\n`) or carriage-return ('\r') characters, [[autoNewLine `autoNewLine`]] stores that value. TODO * If `text` contains either the newline (`\n`) or carriage-return ('\r') characters, [[autoNewLine `autoNewLine`]] stores that value.
* *
**/ **/
this.$detectNewLine = function(text) { this.$detectNewLine = function(text) {
@ -641,10 +647,11 @@ var EditSession = function(text, mode) {
/** /**
* EditSession.getWordRange(row, column) -> Range * EditSession.getWordRange(row, column) -> Range
* - row (Number): The row to check * - row (Number): The row to start at
* - column (Number): The column to check * - 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.
* *
* TODO
**/ **/
this.getWordRange = function(row, column) { this.getWordRange = function(row, column) {
var line = this.getLine(row); var line = this.getLine(row);
@ -694,30 +701,33 @@ var EditSession = function(text, mode) {
return wordRange; return wordRange;
}; };
/** /** related to: Document.setNewLineMode
* EditSession.setNewLineMode(newLineMode) -> Void * EditSession.setNewLineMode(newLineMode) -> Void
* - newLineMode (String): * - newLineMode (String): (~~Document.setNewLineMode.param)
* *
* TODO * (~~Document.setNewLineMode.desc)
**/ **/
this.setNewLineMode = function(newLineMode) { this.setNewLineMode = function(newLineMode) {
this.doc.setNewLineMode(newLineMode); this.doc.setNewLineMode(newLineMode);
}; };
/** /** related to: Document.getNewLineMode
* EditSession.getNewLineMode() -> String * EditSession.getNewLineMode() -> String
* *
* TODO Returns the current new line mode. * Returns the current new line mode.
**/ **/
this.getNewLineMode = function() { this.getNewLineMode = function() {
return this.doc.getNewLineMode(); return this.doc.getNewLineMode();
}; };
this.$useWorker = true; this.$useWorker = true;
/** /**
* EditSession.setUseWorker(useWorker) -> Void * EditSession.setUseWorker(useWorker) -> Void
* - useWorker (Boolean): Set to `true` to use a worker
* *
* TODO * Identifies if you want to use a worker for the `EditSession`.
*
**/ **/
this.setUseWorker = function(useWorker) { this.setUseWorker = function(useWorker) {
if (this.$useWorker == useWorker) if (this.$useWorker == useWorker)
@ -733,7 +743,7 @@ var EditSession = function(text, mode) {
/** /**
* EditSession.getUseWorker() -> Boolean * EditSession.getUseWorker() -> Boolean
* *
* TODO * Returns `true` if workers are being used.
**/ **/
this.getUseWorker = function() { this.getUseWorker = function() {
return this.$useWorker; return this.$useWorker;
@ -753,8 +763,10 @@ var EditSession = function(text, mode) {
this.$mode = null; this.$mode = null;
/** /**
* EditSession.setMode(mode) -> Void * EditSession.setMode(mode) -> Void
* * - mode (TextMode): Set a new text mode
* TODO *
* 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.
*
**/ **/
this.setMode = function(mode) { this.setMode = function(mode) {
if (this.$mode === mode) return; if (this.$mode === mode) return;
@ -793,6 +805,11 @@ var EditSession = function(text, mode) {
this._emit("changeMode"); this._emit("changeMode");
}; };
/** internal
* EditSession.stopWorker() -> Void
*
*
**/
this.$stopWorker = function() { this.$stopWorker = function() {
if (this.$worker) if (this.$worker)
this.$worker.terminate(); this.$worker.terminate();
@ -800,6 +817,11 @@ var EditSession = function(text, mode) {
this.$worker = null; this.$worker = null;
}; };
/** internal
* EditSession.setMode(mode) -> Void
*
*
**/
this.$startWorker = function() { this.$startWorker = function() {
if (typeof Worker !== "undefined" && !require.noWorker) { if (typeof Worker !== "undefined" && !require.noWorker) {
try { try {
@ -815,9 +837,9 @@ var EditSession = function(text, mode) {
}; };
/** /**
* EditSession.getMode() -> String * EditSession.getMode() -> TextMode
* *
* TODO Returns the current mode. * Returns the current text mode.
**/ **/
this.getMode = function() { this.getMode = function() {
return this.$mode; return this.$mode;
@ -826,8 +848,9 @@ var EditSession = function(text, mode) {
this.$scrollTop = 0; this.$scrollTop = 0;
/** /**
* EditSession.setScrollTop(scrollTop) -> Void * EditSession.setScrollTop(scrollTop) -> Void
* * - scrollTop (Number): The new scroll top value
* This function also emits the `'changeScrollTop'` event. TODO *
* This function sets the scroll top value. It also emits the `'changeScrollTop'` event.
**/ **/
this.setScrollTop = function(scrollTop) { this.setScrollTop = function(scrollTop) {
scrollTop = Math.round(Math.max(0, scrollTop)); scrollTop = Math.round(Math.max(0, scrollTop));
@ -964,9 +987,9 @@ var EditSession = function(text, mode) {
/** related to: Document.getTextRange /** related to: Document.getTextRange
* EditSession.getTextRange(range) -> Array * EditSession.getTextRange(range) -> Array
* - range (String): blah * - range (String): The range to work with
* *
* TODO * (~Document.getTextRange.desc)
**/ **/
this.getTextRange = function(range) { this.getTextRange = function(range) {
return this.doc.getTextRange(range); return this.doc.getTextRange(range);
@ -1004,7 +1027,7 @@ var EditSession = function(text, mode) {
/** /**
* EditSession.undoChanges(deltas, dontSelect) -> Range * EditSession.undoChanges(deltas, dontSelect) -> Range
* - deltas (Array): * - deltas (Array):
* - dontSelect (Boolean): * - dontSelect (Boolean):
* *
* TODO * TODO
@ -1074,10 +1097,10 @@ var EditSession = function(text, mode) {
this.$undoSelect = enable; this.$undoSelect = enable;
}; };
/** /** internal
* EditSession.$getUndoSelection(deltas, isUndo, lastUndoRange) -> Range * EditSession.$getUndoSelection(deltas, isUndo, lastUndoRange) -> Range
* *
* TODO *
**/ **/
this.$getUndoSelection = function(deltas, isUndo, lastUndoRange) { this.$getUndoSelection = function(deltas, isUndo, lastUndoRange) {
function isInsert(delta) { function isInsert(delta) {
@ -1379,8 +1402,9 @@ var EditSession = function(text, mode) {
/** /**
* EditSession.setUseWrapMode(useWrapMode) -> Void * EditSession.setUseWrapMode(useWrapMode) -> Void
* * - useWrapMode (Boolean): Enable (or disable) wrap mode
* TODO line wrapping ? *
* 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) { this.setUseWrapMode = function(useWrapMode) {
if (useWrapMode != this.$useWrapMode) { if (useWrapMode != this.$useWrapMode) {
@ -1417,8 +1441,10 @@ var EditSession = function(text, mode) {
// the limit to that value. // the limit to that value.
/** /**
* EditSession.setWrapLimitRange(min, max) -> Void * EditSession.setWrapLimitRange(min, max) -> Void
* * - min (Number): The minimum wrap value (the left side wrap)
* TODO At what point to 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.
**/ **/
this.setWrapLimitRange = function(min, max) { this.setWrapLimitRange = function(min, max) {
if (this.$wrapLimitRange.min !== min || this.$wrapLimitRange.max !== max) { if (this.$wrapLimitRange.min !== min || this.$wrapLimitRange.max !== max) {
@ -1453,6 +1479,11 @@ var EditSession = function(text, mode) {
return false; return false;
}; };
/** internal
* EditSession.$constrainWrapLimit(wrapLimit) -> Void
*
*
**/
this.$constrainWrapLimit = function(wrapLimit) { this.$constrainWrapLimit = function(wrapLimit) {
var min = this.$wrapLimitRange.min; var min = this.$wrapLimitRange.min;
if (min) if (min)
@ -1491,6 +1522,11 @@ var EditSession = function(text, mode) {
}; };
}; };
/** internal
* EditSession.$updateInternalDataOnChange() -> Void
*
*
**/
this.$updateInternalDataOnChange = function(e) { this.$updateInternalDataOnChange = function(e) {
var useWrapMode = this.$useWrapMode; var useWrapMode = this.$useWrapMode;
var len; var len;
@ -1606,6 +1642,11 @@ var EditSession = function(text, mode) {
return removedFolds; return removedFolds;
}; };
/** internal
* EditSession.$updateWrapData(firstRow, lastRow) -> Void
*
*
**/
this.$updateWrapData = function(firstRow, lastRow) { this.$updateWrapData = function(firstRow, lastRow) {
var lines = this.doc.getAllLines(); var lines = this.doc.getAllLines();
var tabSize = this.getTabSize(); var tabSize = this.getTabSize();
@ -1665,6 +1706,11 @@ var EditSession = function(text, mode) {
TAB = 11, TAB = 11,
TAB_SPACE = 12; TAB_SPACE = 12;
/** internal
* EditSession.$computeWrapSplits(tokens, wrapLimit) -> Void
*
*
**/
this.$computeWrapSplits = function(tokens, wrapLimit) { this.$computeWrapSplits = function(tokens, wrapLimit) {
if (tokens.length == 0) { if (tokens.length == 0) {
return []; return [];
@ -1781,6 +1827,13 @@ var EditSession = function(text, mode) {
return splits; return splits;
} }
/** internal
* 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.
**/
this.$getDisplayTokens = function(str, offset) { this.$getDisplayTokens = function(str, offset) {
var arr = []; var arr = [];
var tabSize; var tabSize;
@ -1812,11 +1865,11 @@ var EditSession = function(text, mode) {
return arr; return arr;
} }
/** /** internal
* EditSession.$getStringScreenWidth(str, maxScreenColumn, screenColumn) -> Array * EditSession.$getStringScreenWidth(str, maxScreenColumn, screenColumn) -> Array
* - str (String): The string to calculate the screen width of * - str (String): The string to calculate the screen width of
* - maxScreenColumn (Integer): TODO * - maxScreenColumn (Integer):
* - screenColumn (Integer): TODO * - screenColumn (Integer):
* *
* Calculates the width of the string `str` on the screen while assuming that the string starts at the first column on the screen. * Calculates the width of the string `str` on the screen while assuming that the string starts at the first column on the screen.
* *
@ -1873,19 +1926,20 @@ var EditSession = function(text, mode) {
/** /**
* EditSession.getRowHeight(config, row) -> Number * EditSession.getRowHeight(config, row) -> Number
* - config (String): TODO * - config (Object): An object containing a parameter indicating the `lineHeight`.
* - row (Number): The row number to check * - row (Number): The row number to check
* *
* Returns the height of the indicated row. * 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) { this.getRowHeight = function(config, row) {
return this.getRowLength(row) * config.lineHeight; return this.getRowLength(row) * config.lineHeight;
} }
/** /** related to: EditSession.documentToScreenColumn
* EditSession.getScreenLastRowColumn(screenRow) -> Number * EditSession.getScreenLastRowColumn(screenRow) -> Number
* * - screenRow (Number): The
*
* TODO * TODO
**/ **/
this.getScreenLastRowColumn = function(screenRow) { this.getScreenLastRowColumn = function(screenRow) {
@ -2061,7 +2115,7 @@ var EditSession = function(text, mode) {
}; };
/** /**
* EditSession.documentToScreenPosition(docRow, docColumn) -> Number * EditSession.documentToScreenPosition(docRow, docColumn) -> Object
* *
* TODO * TODO
**/ **/

75
lib/ace/editor.js
View file

@ -61,16 +61,16 @@ var defaultCommands = require("./commands/default_commands").commands;
/** /**
* class Editor * class Editor
* *
* Some editor stuff. TODO * The main entry point into the Ace functionality. The `Editor` manages the `EditSession` (which manages `Document`s), as well as the `VirtualRenderer`, which draws everything to the screen. Event sessions dealing with the mouse and keyboard are bubbled up from `Document` to the `Editor`, which decides what to do with them.
* *
**/ **/
/** /**
* new Editor(renderer, session) * new Editor(renderer, session)
* - renderer (VirtualRenderer): * - renderer (VirtualRenderer): Associated `VirtualRenderer` that draws everything
* - session (EditSession): * - session (EditSession): The `EditSession` to refer to
* *
* Creates a new `Editor`. TODO * Creates a new `Editor` object.
* *
**/ **/
var Editor = function(renderer, session) { var Editor = function(renderer, session) {
@ -78,12 +78,6 @@ var Editor = function(renderer, session) {
this.container = container; this.container = container;
this.renderer = renderer; this.renderer = renderer;
/**
* Editor.textInput -> TextInput
*
* The current text editable area of the document.
*
**/
this.textInput = new TextInput(renderer.getTextAreaContainer(), this); this.textInput = new TextInput(renderer.getTextAreaContainer(), this);
this.keyBinding = new KeyBinding(this); this.keyBinding = new KeyBinding(this);
@ -117,10 +111,10 @@ var Editor = function(renderer, session) {
this.keyBinding.setKeyboardHandler(keyboardHandler); this.keyBinding.setKeyboardHandler(keyboardHandler);
}; };
/** /** related to: KeyBinding
* Editor.getKeyboardHandler() -> String * Editor.getKeyboardHandler() -> String
* *
* TODO Returns a keyboard handler. * Returns the keyboard handler.
**/ **/
this.getKeyboardHandler = function() { this.getKeyboardHandler = function() {
return this.keyBinding.getKeyboardHandler(); return this.keyBinding.getKeyboardHandler();
@ -130,7 +124,7 @@ var Editor = function(renderer, session) {
* Editor.setSession(session) -> Void * Editor.setSession(session) -> Void
* - session (EditSession): The new session to use * - session (EditSession): The new session to use
* *
* Sets a new session to use. This method also emits the `'changeSession'` event. * Sets a new editsession to use. This method also emits the `'changeSession'` event.
**/ **/
this.setSession = function(session) { this.setSession = function(session) {
if (this.session == session) if (this.session == session)
@ -243,16 +237,16 @@ var Editor = function(renderer, session) {
/** /**
* Editor.getSelection() -> String * Editor.getSelection() -> String
* *
* TODO * Returns the currently highlighted selection.
**/ **/
this.getSelection = function() { this.getSelection = function() {
return this.selection; return this.selection;
}; };
/**related to: VirtualRenderer.onResize /** related to: VirtualRenderer.onResize
* Editor.resize() -> Void * Editor.resize() -> Void
* *
* * (~VirtualRenderer.onResize)
**/ **/
this.resize = function() { this.resize = function() {
this.renderer.onResize(); this.renderer.onResize();
@ -305,10 +299,10 @@ var Editor = function(renderer, session) {
this.renderer.updateFontSize(); this.renderer.updateFontSize();
}; };
/** /** internal
* Editor.$highlightBrackets() -> Void * Editor.$highlightBrackets() -> Void
* *
* TODO Highlights matching * TODO
**/ **/
this.$highlightBrackets = function() { this.$highlightBrackets = function() {
if (this.session.$bracketHighlight) { if (this.session.$bracketHighlight) {
@ -426,9 +420,9 @@ var Editor = function(renderer, session) {
}; };
/** /**
* Editor@onScrollTopChange() * Editor@onScrollTopChange() -> Void
*
* *
* TODO Emitted when the top
**/ **/
this.onScrollTopChange = function() { this.onScrollTopChange = function() {
this.renderer.scrollToY(this.session.getScrollTop()); this.renderer.scrollToY(this.session.getScrollTop());
@ -437,7 +431,7 @@ var Editor = function(renderer, session) {
/** /**
* Editor@onScrollLeftChange() * Editor@onScrollLeftChange()
* *
* TODO Emitted when *
**/ **/
this.onScrollLeftChange = function() { this.onScrollLeftChange = function() {
this.renderer.scrollToX(this.session.getScrollLeft()); this.renderer.scrollToX(this.session.getScrollLeft());
@ -446,7 +440,7 @@ var Editor = function(renderer, session) {
/** /**
* Editor@onCursorChange() * Editor@onCursorChange()
* *
* TODO Emitted whenever the cursor changes. *
**/ **/
this.onCursorChange = function() { this.onCursorChange = function() {
this.renderer.updateCursor(); this.renderer.updateCursor();
@ -463,6 +457,11 @@ var Editor = function(renderer, session) {
this.$updateHighlightActiveLine(); this.$updateHighlightActiveLine();
}; };
/** internal
* Editor.$updateHighlightActiveLine()
*
*
**/
this.$updateHighlightActiveLine = function() { this.$updateHighlightActiveLine = function() {
var session = this.getSession(); var session = this.getSession();
@ -622,7 +621,7 @@ var Editor = function(renderer, session) {
* Editor.insert(text) -> Void * Editor.insert(text) -> Void
* - text (String): The new text to add * - text (String): The new text to add
* *
* TODO Inserts `text` into wherever the cursor is pointing. * Inserts `text` into wherever the cursor is pointing.
**/ **/
this.insert = function(text) { this.insert = function(text) {
var session = this.session; var session = this.session;
@ -718,8 +717,10 @@ var Editor = function(renderer, session) {
/** /**
* Editor@onTextInput(text, pasted) * Editor@onTextInput(text, pasted)
* * - text (String): The text entered
* TODO * - pasted (Boolean): Identifies whether the text was pasted (`true`) or not
*
* Emitted when text is entered.
**/ **/
this.onTextInput = function(text, pasted) { this.onTextInput = function(text, pasted) {
if (pasted) if (pasted)
@ -731,7 +732,7 @@ var Editor = function(renderer, session) {
/** /**
* Editor@onCommandKey(e, hashId, keyCode) * Editor@onCommandKey(e, hashId, keyCode)
* *
* TODO * Emitted when the command-key is pressed.
**/ **/
this.onCommandKey = function(e, hashId, keyCode) { this.onCommandKey = function(e, hashId, keyCode) {
this.keyBinding.onCommandKey(e, hashId, keyCode); this.keyBinding.onCommandKey(e, hashId, keyCode);
@ -790,7 +791,7 @@ var Editor = function(renderer, session) {
* Editor.setDragDelay(dragDelay) -> Void * Editor.setDragDelay(dragDelay) -> Void
* - dragDelay (Number): A value indicating the new delay * - dragDelay (Number): A value indicating the new delay
* *
* TODO Sets the delay (in milliseconds) of the mouse drag. * Sets the delay (in milliseconds) of the mouse drag.
* *
**/ **/
this.setDragDelay = function(dragDelay) { this.setDragDelay = function(dragDelay) {
@ -968,9 +969,9 @@ var Editor = function(renderer, session) {
/** /**
* Editor.setBehavioursEnabled() -> Void * Editor.setBehavioursEnabled() -> Void
* - enabled (Boolean) * - enabled (Boolean): Enables or disables behaviors
* *
*TODO * Specifies whether to use behaviors or not. ["Behaviors" in this case is the auto-pairing of special characters, like quotation marks, parenthesis, or brackets.](~BehaviorsDef)
**/ **/
this.setBehavioursEnabled = function (enabled) { this.setBehavioursEnabled = function (enabled) {
this.$modeBehaviours = enabled; this.$modeBehaviours = enabled;
@ -979,7 +980,7 @@ var Editor = function(renderer, session) {
/** /**
* Editor.getBehavioursEnabled() -> Boolean * Editor.getBehavioursEnabled() -> Boolean
* *
* TODO Returns `true` if the behaviours are currently enabled. * Returns `true` if the behaviors are currently enabled. (~BehaviorsDef)
**/ **/
this.getBehavioursEnabled = function () { this.getBehavioursEnabled = function () {
@ -1116,7 +1117,7 @@ var Editor = function(renderer, session) {
/** /**
* Editor.transposeLetters() -> Void * Editor.transposeLetters() -> Void
* *
* Transposes the letters of the entire line . TODO * Transposes current line.
**/ **/
this.transposeLetters = function() { this.transposeLetters = function() {
if (!this.selection.isEmpty()) { if (!this.selection.isEmpty()) {
@ -1891,7 +1892,7 @@ var Editor = function(renderer, session) {
/** related to: Search.getOptions /** related to: Search.getOptions
* Editor.getLastSearchOptions() -> Object * Editor.getLastSearchOptions() -> Object
* *
* (~Search.getOptions) * (~Search.getOptions) For more information on `options`, see [[Search `Search`]].
**/ **/
this.getLastSearchOptions = function() { this.getLastSearchOptions = function() {
return this.$search.getOptions(); return this.$search.getOptions();
@ -1899,8 +1900,10 @@ var Editor = function(renderer, session) {
/** related to: Search.find /** related to: Search.find
* Editor.find(needle, options) -> Void * Editor.find(needle, options) -> Void
* * - needle (String): The text to search for
* TODO * - options (Object): An object defining various search properties
*
* Attempts to find `needle` within the document. For more information on `options`, see [[Search `Search`]].
**/ **/
this.find = function(needle, options) { this.find = function(needle, options) {
this.clearSelection(); this.clearSelection();
@ -1913,7 +1916,7 @@ var Editor = function(renderer, session) {
/** related to: Editor.find /** related to: Editor.find
* Editor.findNext(options) -> Void * Editor.findNext(options) -> Void
* *
* Performs another search for `needle` in the document. * Performs another search for `needle` in the document. For more information on `options`, see [[Search `Search`]].
**/ **/
this.findNext = function(options) { this.findNext = function(options) {
options = options || {}; options = options || {};
@ -1926,7 +1929,7 @@ var Editor = function(renderer, session) {
/** related to: Editor.find /** related to: Editor.find
* Editor.findPrevious(options) -> Void * Editor.findPrevious(options) -> Void
* *
* Performs a search for `needle` backwards. * Performs a search for `needle` backwards. For more information on `options`, see [[Search `Search`]].
**/ **/
this.findPrevious = function(options) { this.findPrevious = function(options) {
options = options || {}; options = options || {};

4
lib/ace/range.js
View file

@ -443,8 +443,8 @@ var Range = function(startRow, startColumn, endRow, endColumn) {
/** /**
* Range.clipRows(firstRow, lastRow) -> Range * Range.clipRows(firstRow, lastRow) -> Range
* - firstRow (Number): * - firstRow (Number): The starting row
* - lastRow (Number): * - lastRow (Number): The ending row
* *
* TODO * TODO
* *

4
lib/ace/scrollbar.js
View file

@ -53,9 +53,9 @@ var EventEmitter = require("./lib/event_emitter").EventEmitter;
/** /**
* new ScrollBar(parent) * new ScrollBar(parent)
* - parent (TODO) * - parent (Element): A DOM element
* *
* Creates a new `ScrollBar`. * Creates a new `ScrollBar`. `parent` is the owner of the scroll bar.
* *
**/ **/
var ScrollBar = function(parent) { var ScrollBar = function(parent) {

10
lib/ace/search.js
View file

@ -47,7 +47,7 @@ var Range = require("./range").Range;
/** /**
* class Search * class Search
* *
* TODO * A class designed to handle all sorts of text searches within a [[Document `Document`]].
* *
**/ **/
@ -192,11 +192,11 @@ Search.SELECTION = 2;
} }
}; };
/** /** internal
* Search.$forwardMatchIterator(session) -> String | Boolean * Search.$forwardMatchIterator(session) -> String | Boolean
* - session (EditSession): The session to search with * - session (EditSession): The session to search with
* *
* TODO--not doing the below $ signs, they look internal *
* *
**/ **/
this.$forwardMatchIterator = function(session) { this.$forwardMatchIterator = function(session) {
@ -233,11 +233,11 @@ Search.SELECTION = 2;
}; };
}; };
/** /** internal
* Search.$backwardMatchIterator(session) -> String | null * Search.$backwardMatchIterator(session) -> String | null
* - session (EditSession): The session to search with * - session (EditSession): The session to search with
* *
* TODO *
* *
**/ **/
this.$backwardMatchIterator = function(session) { this.$backwardMatchIterator = function(session) {

2
lib/ace/tokenizer.js
View file

@ -94,7 +94,7 @@ var Tokenizer = function(rules, flag) {
/** /**
* Tokenizer.getLineTokens() -> Object * Tokenizer.getLineTokens() -> Object
* *
* TODO. Returns an object containing two properties: `tokens`, all the tokens; and `state`, the current state. * TODO. Returns an object containing two properties: `tokens`, which contains all the tokens; and `state`, the current state.
**/ **/
this.getLineTokens = function(line, startState) { this.getLineTokens = function(line, startState) {
var currentState = startState; var currentState = startState;

8
lib/ace/virtual_renderer.js
View file

@ -265,7 +265,7 @@ var VirtualRenderer = function(container, theme) {
* VirtualRenderer.onResize(force) -> Void * VirtualRenderer.onResize(force) -> Void
* - force (Boolean): TODO * - force (Boolean): TODO
* *
* Triggers a resize of the editor. * [Triggers a resize of the editor.](~VirtualRenderer.onResize)
**/ **/
this.onResize = function(force) { this.onResize = function(force) {
var changes = this.CHANGE_SIZE; var changes = this.CHANGE_SIZE;
@ -796,9 +796,9 @@ var VirtualRenderer = function(container, theme) {
/** /**
* VirtualRenderer.setAnnotations(annotations) -> Void * VirtualRenderer.setAnnotations(annotations) -> Void
* - annotations (Array): An array containing annotation * - annotations (Array): An array containing annotations
* *
* TODO * Sets annotations for the gutter.
**/ **/
this.setAnnotations = function(annotations) { this.setAnnotations = function(annotations) {
this.$gutterLayer.setAnnotations(annotations); this.$gutterLayer.setAnnotations(annotations);
@ -1177,7 +1177,7 @@ var VirtualRenderer = function(container, theme) {
/** /**
* VirtualRenderer.destroy() * VirtualRenderer.destroy()
* *
* TODO * Destroys the text and cursor layers for this renderer.
**/ **/
this.destroy = function() { this.destroy = function() {
this.$textLayer.destroy(); this.$textLayer.destroy();