From 554b845bb9e20ce917e986d703c0def3a1543e8f Mon Sep 17 00:00:00 2001 From: Garen Torikian Date: Tue, 7 Feb 2012 16:22:22 -0800 Subject: [PATCH] Make some updates to doc --- .../ace/skins/skeleton/images/Ace_ERD.svg | 4 + lib/ace/ace.js | 6 +- lib/ace/anchor.js | 8 +- lib/ace/background_tokenizer.js | 8 +- lib/ace/document.js | 55 ++--- lib/ace/edit_session.js | 192 +++++++++++------- lib/ace/editor.js | 75 +++---- lib/ace/range.js | 4 +- lib/ace/scrollbar.js | 4 +- lib/ace/search.js | 10 +- lib/ace/tokenizer.js | 2 +- lib/ace/virtual_renderer.js | 8 +- 12 files changed, 219 insertions(+), 157 deletions(-) create mode 100644 doc/resources/ace/skins/skeleton/images/Ace_ERD.svg diff --git a/doc/resources/ace/skins/skeleton/images/Ace_ERD.svg b/doc/resources/ace/skins/skeleton/images/Ace_ERD.svg new file mode 100644 index 00000000..ba386287 --- /dev/null +++ b/doc/resources/ace/skins/skeleton/images/Ace_ERD.svg @@ -0,0 +1,4 @@ + + + + diff --git a/lib/ace/ace.js b/lib/ace/ace.js index 3e4d85d9..9f9c67dd 100644 --- a/lib/ace/ace.js +++ b/lib/ace/ace.js @@ -38,7 +38,7 @@ /** * 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 - * - 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) { diff --git a/lib/ace/anchor.js b/lib/ace/anchor.js index 2f54fdf5..6fcdef01 100644 --- a/lib/ace/anchor.js +++ b/lib/ace/anchor.js @@ -98,9 +98,9 @@ var Anchor = exports.Anchor = function(doc, row, column) { /** * 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); }; - /** + /** internal * Anchor.clipPositionToDocument(row, column) -> Void * - row (Number): The row 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. * **/ diff --git a/lib/ace/background_tokenizer.js b/lib/ace/background_tokenizer.js index 804fe9a5..2cc7309c 100644 --- a/lib/ace/background_tokenizer.js +++ b/lib/ace/background_tokenizer.js @@ -44,7 +44,7 @@ var EventEmitter = require("./lib/event_emitter").EventEmitter; /** * 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); }; - /** related to: BackgroundTokenizer.$tokenizeRows - * BackgroundTokenizer.getState(row) -> Array + /** + * BackgroundTokenizer.getState(row) -> String * - 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) * **/ diff --git a/lib/ace/document.js b/lib/ace/document.js index 93488c29..b8a8d12c 100644 --- a/lib/ace/document.js +++ b/lib/ace/document.js @@ -46,16 +46,16 @@ var Anchor = require("./anchor").Anchor; /** * 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 * - * 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) { @@ -77,11 +77,11 @@ var Document = function(text) { oop.implement(this, EventEmitter); - /** + /** * 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) { var len = this.getLength(); @@ -89,25 +89,27 @@ var Document = function(text) { this.insert({row: 0, column:0}, text); }; - /** + /** * 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() { return this.getAllLines().join(this.getNewLineCharacter()); }; - /** + /** * 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) { return new Anchor(this, row, column); }; - /** + /** internal * Document.$split(text) -> Array * - text (String): The text to work with * @@ -130,7 +132,7 @@ var Document = function(text) { }; - /** + /** internal * Document.$detectNewLine(text) -> Void * * @@ -147,7 +149,7 @@ var Document = function(text) { /** * 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 * @@ -174,9 +176,9 @@ var Document = function(text) { this.$newLineMode = "auto"; /** * 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) { if (this.$newLineMode === newLineMode) @@ -188,7 +190,7 @@ var Document = function(text) { /** * 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() { @@ -248,10 +250,10 @@ var Document = function(text) { }; /** - * Document.getTextRange(range) -> Array - * - range (String): blah + * Document.getTextRange(range) -> String + * - 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) { if (range.start.row == range.end.row) { @@ -267,11 +269,10 @@ var Document = function(text) { } }; - /** + /** internal * Document.$clipPosition(position) -> Number - * - position (Number): blah * - * TODO + * **/ this.$clipPosition = function(position) { var length = this.getLength(); @@ -529,9 +530,9 @@ var Document = function(text) { /** * 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) { @@ -592,7 +593,7 @@ var Document = function(text) { /** * Document.applyDeltas(deltas) -> Void * - * TODO + * Applies all the changes previously accumulated. These can be either `'includeText'`, `'insertLines'`, `'removeText'`, and `'removeLines'`. **/ this.applyDeltas = function(deltas) { for (var i=0; i Void * - * TODO + * Reverts any changes previously applied. These can be either `'includeText'`, `'insertLines'`, `'removeText'`, and `'removeLines'`. **/ this.revertDeltas = function(deltas) { for (var i=deltas.length-1; i>=0; i--) { diff --git a/lib/ace/edit_session.js b/lib/ace/edit_session.js index db2da306..9b0fc8e7 100644 --- a/lib/ace/edit_session.js +++ b/lib/ace/edit_session.js @@ -53,16 +53,16 @@ var BackgroundTokenizer = require("./background_tokenizer").BackgroundTokenizer; /** * 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) - * - text (String): Some text - * - mode (Boolean): A boolean + * - 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 * - * 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 - * - 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) { @@ -133,11 +133,11 @@ var EditSession = function(text, mode) { return this.doc; }; - /** + /** internal * EditSession.$resetRowCache(row) -> Void * - row (Number): The row to work with * - * TODO Does some stuff. + * * **/ this.$resetRowCache = function(row) { @@ -155,10 +155,9 @@ var EditSession = function(text, mode) { }; /** - * EditSession@onChangeFold(e) + * EditSession@onChangeFold(e) -> Void * - * - * This event triggers when code folds change their state. TODO + * Emitted when a code fold changes its state. * **/ 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) { var delta = e.data; @@ -213,13 +212,19 @@ var EditSession = function(text, mode) { this.getUndoManager().reset(); }; - this.getValue = - /** - * EditSession.toString() -> String - * - * Returns the current [[Document `Document`]] as a string. + /** alias of: EditSession.toString() + * EditSession.getValue() -> 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() { return this.doc.getValue(); }; @@ -237,7 +242,7 @@ var EditSession = function(text, mode) { * EditSession.getState(row) -> Array * - 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) { @@ -302,10 +307,10 @@ var EditSession = function(text, mode) { if (undoManager) { var self = this; - /** + /** internal * EditSession.$syncInformUndoManager() -> Void * - * TODO + * **/ this.$syncInformUndoManager = function() { self.$informUndoManager.cancel(); @@ -418,9 +423,9 @@ var EditSession = function(text, mode) { /** * 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) { return this.$useSoftTabs && (position.column % this.$tabSize == 0); @@ -516,13 +521,14 @@ var EditSession = function(text, mode) { }; /** - * EditSession.addMarker(range, clazz, type, inFront) -> Number - * - range (Range): - * - clazz (String): - * - type (String): - * - inFront (Boolean): + * 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. * - * TODO **/ this.addMarker = function(range, clazz, type, inFront) { var id = this.$markerId++; @@ -587,9 +593,9 @@ var EditSession = function(text, mode) { */ /** * 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.$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() { return this.$annotations || {}; @@ -623,11 +629,11 @@ var EditSession = function(text, mode) { this._emit("changeAnnotation", {}); }; - /** + /** internal * EditSession.$detectNewLine(text) -> Void * - 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) { @@ -641,10 +647,11 @@ var EditSession = function(text, mode) { /** * EditSession.getWordRange(row, column) -> Range - * - row (Number): The row to check - * - column (Number): The column to check + * - 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. * - * TODO **/ this.getWordRange = function(row, column) { var line = this.getLine(row); @@ -694,30 +701,33 @@ var EditSession = function(text, mode) { return wordRange; }; - /** + /** related to: Document.setNewLineMode * EditSession.setNewLineMode(newLineMode) -> Void - * - newLineMode (String): + * - newLineMode (String): (~~Document.setNewLineMode.param) * - * TODO + * (~~Document.setNewLineMode.desc) **/ this.setNewLineMode = function(newLineMode) { this.doc.setNewLineMode(newLineMode); }; - /** + /** related to: Document.getNewLineMode * EditSession.getNewLineMode() -> String * - * TODO Returns the current new line mode. + * Returns the current new line mode. **/ this.getNewLineMode = function() { return this.doc.getNewLineMode(); }; this.$useWorker = true; + /** * 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) { if (this.$useWorker == useWorker) @@ -733,7 +743,7 @@ var EditSession = function(text, mode) { /** * EditSession.getUseWorker() -> Boolean * - * TODO + * Returns `true` if workers are being used. **/ this.getUseWorker = function() { return this.$useWorker; @@ -753,8 +763,10 @@ var EditSession = function(text, mode) { this.$mode = null; /** * EditSession.setMode(mode) -> Void - * - * TODO + * - 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. + * **/ this.setMode = function(mode) { if (this.$mode === mode) return; @@ -793,6 +805,11 @@ var EditSession = function(text, mode) { this._emit("changeMode"); }; + /** internal + * EditSession.stopWorker() -> Void + * + * + **/ this.$stopWorker = function() { if (this.$worker) this.$worker.terminate(); @@ -800,6 +817,11 @@ var EditSession = function(text, mode) { this.$worker = null; }; + /** internal + * EditSession.setMode(mode) -> Void + * + * + **/ this.$startWorker = function() { if (typeof Worker !== "undefined" && !require.noWorker) { 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() { return this.$mode; @@ -826,8 +848,9 @@ var EditSession = function(text, mode) { this.$scrollTop = 0; /** * EditSession.setScrollTop(scrollTop) -> Void - * - * This function also emits the `'changeScrollTop'` event. TODO + * - scrollTop (Number): The new scroll top value + * + * This function sets the scroll top value. It also emits the `'changeScrollTop'` event. **/ this.setScrollTop = function(scrollTop) { scrollTop = Math.round(Math.max(0, scrollTop)); @@ -964,9 +987,9 @@ var EditSession = function(text, mode) { /** related to: Document.getTextRange * EditSession.getTextRange(range) -> Array - * - range (String): blah + * - range (String): The range to work with * - * TODO + * (~Document.getTextRange.desc) **/ this.getTextRange = function(range) { return this.doc.getTextRange(range); @@ -1004,7 +1027,7 @@ var EditSession = function(text, mode) { /** * EditSession.undoChanges(deltas, dontSelect) -> Range - * - deltas (Array): + * - deltas (Array): * - dontSelect (Boolean): * * TODO @@ -1074,10 +1097,10 @@ var EditSession = function(text, mode) { this.$undoSelect = enable; }; - /** + /** internal * EditSession.$getUndoSelection(deltas, isUndo, lastUndoRange) -> Range * - * TODO + * **/ this.$getUndoSelection = function(deltas, isUndo, lastUndoRange) { function isInsert(delta) { @@ -1379,8 +1402,9 @@ var EditSession = function(text, mode) { /** * EditSession.setUseWrapMode(useWrapMode) -> Void - * - * TODO line wrapping ? + * - 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. **/ this.setUseWrapMode = function(useWrapMode) { if (useWrapMode != this.$useWrapMode) { @@ -1417,8 +1441,10 @@ var EditSession = function(text, mode) { // the limit to that value. /** * EditSession.setWrapLimitRange(min, max) -> Void - * - * TODO At what point to wrap ? + * - 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. **/ this.setWrapLimitRange = function(min, max) { if (this.$wrapLimitRange.min !== min || this.$wrapLimitRange.max !== max) { @@ -1453,6 +1479,11 @@ var EditSession = function(text, mode) { return false; }; + /** internal + * EditSession.$constrainWrapLimit(wrapLimit) -> Void + * + * + **/ this.$constrainWrapLimit = function(wrapLimit) { var min = this.$wrapLimitRange.min; if (min) @@ -1491,6 +1522,11 @@ var EditSession = function(text, mode) { }; }; + /** internal + * EditSession.$updateInternalDataOnChange() -> Void + * + * + **/ this.$updateInternalDataOnChange = function(e) { var useWrapMode = this.$useWrapMode; var len; @@ -1606,6 +1642,11 @@ var EditSession = function(text, mode) { return removedFolds; }; + /** internal + * EditSession.$updateWrapData(firstRow, lastRow) -> Void + * + * + **/ this.$updateWrapData = function(firstRow, lastRow) { var lines = this.doc.getAllLines(); var tabSize = this.getTabSize(); @@ -1665,6 +1706,11 @@ var EditSession = function(text, mode) { TAB = 11, TAB_SPACE = 12; + /** internal + * EditSession.$computeWrapSplits(tokens, wrapLimit) -> Void + * + * + **/ this.$computeWrapSplits = function(tokens, wrapLimit) { if (tokens.length == 0) { return []; @@ -1781,6 +1827,13 @@ var EditSession = function(text, mode) { 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) { var arr = []; var tabSize; @@ -1812,11 +1865,11 @@ var EditSession = function(text, mode) { return arr; } - /** + /** internal * EditSession.$getStringScreenWidth(str, maxScreenColumn, screenColumn) -> Array * - str (String): The string to calculate the screen width of - * - maxScreenColumn (Integer): TODO - * - screenColumn (Integer): TODO + * - maxScreenColumn (Integer): + * - 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. * @@ -1873,19 +1926,20 @@ var EditSession = function(text, mode) { /** * 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 * - * 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) { return this.getRowLength(row) * config.lineHeight; } - /** + /** related to: EditSession.documentToScreenColumn * EditSession.getScreenLastRowColumn(screenRow) -> Number - * + * - screenRow (Number): The + * * TODO **/ this.getScreenLastRowColumn = function(screenRow) { @@ -2061,7 +2115,7 @@ var EditSession = function(text, mode) { }; /** - * EditSession.documentToScreenPosition(docRow, docColumn) -> Number + * EditSession.documentToScreenPosition(docRow, docColumn) -> Object * * TODO **/ diff --git a/lib/ace/editor.js b/lib/ace/editor.js index 666f4c66..45b14074 100644 --- a/lib/ace/editor.js +++ b/lib/ace/editor.js @@ -61,16 +61,16 @@ var defaultCommands = require("./commands/default_commands").commands; /** * 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) - * - renderer (VirtualRenderer): - * - session (EditSession): + * - renderer (VirtualRenderer): Associated `VirtualRenderer` that draws everything + * - session (EditSession): The `EditSession` to refer to * - * Creates a new `Editor`. TODO + * Creates a new `Editor` object. * **/ var Editor = function(renderer, session) { @@ -78,12 +78,6 @@ var Editor = function(renderer, session) { this.container = container; this.renderer = renderer; - /** - * Editor.textInput -> TextInput - * - * The current text editable area of the document. - * - **/ this.textInput = new TextInput(renderer.getTextAreaContainer(), this); this.keyBinding = new KeyBinding(this); @@ -117,10 +111,10 @@ var Editor = function(renderer, session) { this.keyBinding.setKeyboardHandler(keyboardHandler); }; - /** + /** related to: KeyBinding * Editor.getKeyboardHandler() -> String * - * TODO Returns a keyboard handler. + * Returns the keyboard handler. **/ this.getKeyboardHandler = function() { return this.keyBinding.getKeyboardHandler(); @@ -130,7 +124,7 @@ var Editor = function(renderer, session) { * Editor.setSession(session) -> Void * - 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) { if (this.session == session) @@ -243,16 +237,16 @@ var Editor = function(renderer, session) { /** * Editor.getSelection() -> String * - * TODO + * Returns the currently highlighted selection. **/ this.getSelection = function() { return this.selection; }; - /**related to: VirtualRenderer.onResize + /** related to: VirtualRenderer.onResize * Editor.resize() -> Void * - * + * (~VirtualRenderer.onResize) **/ this.resize = function() { this.renderer.onResize(); @@ -305,10 +299,10 @@ var Editor = function(renderer, session) { this.renderer.updateFontSize(); }; - /** + /** internal * Editor.$highlightBrackets() -> Void * - * TODO Highlights matching + * TODO **/ this.$highlightBrackets = function() { 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.renderer.scrollToY(this.session.getScrollTop()); @@ -437,7 +431,7 @@ var Editor = function(renderer, session) { /** * Editor@onScrollLeftChange() * - * TODO Emitted when + * **/ this.onScrollLeftChange = function() { this.renderer.scrollToX(this.session.getScrollLeft()); @@ -446,7 +440,7 @@ var Editor = function(renderer, session) { /** * Editor@onCursorChange() * - * TODO Emitted whenever the cursor changes. + * **/ this.onCursorChange = function() { this.renderer.updateCursor(); @@ -463,6 +457,11 @@ var Editor = function(renderer, session) { this.$updateHighlightActiveLine(); }; + /** internal + * Editor.$updateHighlightActiveLine() + * + * + **/ this.$updateHighlightActiveLine = function() { var session = this.getSession(); @@ -622,7 +621,7 @@ var Editor = function(renderer, session) { * Editor.insert(text) -> Void * - 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) { var session = this.session; @@ -718,8 +717,10 @@ var Editor = function(renderer, session) { /** * Editor@onTextInput(text, pasted) - * - * TODO + * - text (String): The text entered + * - pasted (Boolean): Identifies whether the text was pasted (`true`) or not + * + * Emitted when text is entered. **/ this.onTextInput = function(text, pasted) { if (pasted) @@ -731,7 +732,7 @@ var Editor = function(renderer, session) { /** * Editor@onCommandKey(e, hashId, keyCode) * - * TODO + * Emitted when the command-key is pressed. **/ this.onCommandKey = function(e, hashId, keyCode) { this.keyBinding.onCommandKey(e, hashId, keyCode); @@ -790,7 +791,7 @@ var Editor = function(renderer, session) { * Editor.setDragDelay(dragDelay) -> Void * - 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) { @@ -968,9 +969,9 @@ var Editor = function(renderer, session) { /** * 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.$modeBehaviours = enabled; @@ -979,7 +980,7 @@ var Editor = function(renderer, session) { /** * Editor.getBehavioursEnabled() -> Boolean * - * TODO Returns `true` if the behaviours are currently enabled. + * Returns `true` if the behaviors are currently enabled. (~BehaviorsDef) **/ this.getBehavioursEnabled = function () { @@ -1116,7 +1117,7 @@ var Editor = function(renderer, session) { /** * Editor.transposeLetters() -> Void * - * Transposes the letters of the entire line . TODO + * Transposes current line. **/ this.transposeLetters = function() { if (!this.selection.isEmpty()) { @@ -1891,7 +1892,7 @@ var Editor = function(renderer, session) { /** related to: Search.getOptions * Editor.getLastSearchOptions() -> Object * - * (~Search.getOptions) + * (~Search.getOptions) For more information on `options`, see [[Search `Search`]]. **/ this.getLastSearchOptions = function() { return this.$search.getOptions(); @@ -1899,8 +1900,10 @@ var Editor = function(renderer, session) { /** related to: Search.find * Editor.find(needle, options) -> Void - * - * TODO + * - needle (String): The text to search for + * - 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.clearSelection(); @@ -1913,7 +1916,7 @@ var Editor = function(renderer, session) { /** related to: Editor.find * 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) { options = options || {}; @@ -1926,7 +1929,7 @@ var Editor = function(renderer, session) { /** related to: Editor.find * 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) { options = options || {}; diff --git a/lib/ace/range.js b/lib/ace/range.js index a0ad29b2..d4a57fbc 100644 --- a/lib/ace/range.js +++ b/lib/ace/range.js @@ -443,8 +443,8 @@ var Range = function(startRow, startColumn, endRow, endColumn) { /** * Range.clipRows(firstRow, lastRow) -> Range - * - firstRow (Number): - * - lastRow (Number): + * - firstRow (Number): The starting row + * - lastRow (Number): The ending row * * TODO * diff --git a/lib/ace/scrollbar.js b/lib/ace/scrollbar.js index 26e9becd..8cd0bf83 100644 --- a/lib/ace/scrollbar.js +++ b/lib/ace/scrollbar.js @@ -53,9 +53,9 @@ var EventEmitter = require("./lib/event_emitter").EventEmitter; /** * 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) { diff --git a/lib/ace/search.js b/lib/ace/search.js index 6ad81b7f..24b73989 100644 --- a/lib/ace/search.js +++ b/lib/ace/search.js @@ -47,7 +47,7 @@ var Range = require("./range").Range; /** * 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 * - session (EditSession): The session to search with * - * TODO--not doing the below $ signs, they look internal + * * **/ this.$forwardMatchIterator = function(session) { @@ -233,11 +233,11 @@ Search.SELECTION = 2; }; }; - /** + /** internal * Search.$backwardMatchIterator(session) -> String | null * - session (EditSession): The session to search with * - * TODO + * * **/ this.$backwardMatchIterator = function(session) { diff --git a/lib/ace/tokenizer.js b/lib/ace/tokenizer.js index 56641804..127d965c 100644 --- a/lib/ace/tokenizer.js +++ b/lib/ace/tokenizer.js @@ -94,7 +94,7 @@ var Tokenizer = function(rules, flag) { /** * 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) { var currentState = startState; diff --git a/lib/ace/virtual_renderer.js b/lib/ace/virtual_renderer.js index 5e59c680..d99287bf 100644 --- a/lib/ace/virtual_renderer.js +++ b/lib/ace/virtual_renderer.js @@ -265,7 +265,7 @@ var VirtualRenderer = function(container, theme) { * VirtualRenderer.onResize(force) -> Void * - force (Boolean): TODO * - * Triggers a resize of the editor. + * [Triggers a resize of the editor.](~VirtualRenderer.onResize) **/ this.onResize = function(force) { var changes = this.CHANGE_SIZE; @@ -796,9 +796,9 @@ var VirtualRenderer = function(container, theme) { /** * 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.$gutterLayer.setAnnotations(annotations); @@ -1177,7 +1177,7 @@ var VirtualRenderer = function(container, theme) { /** * VirtualRenderer.destroy() * - * TODO + * Destroys the text and cursor layers for this renderer. **/ this.destroy = function() { this.$textLayer.destroy();