diff --git a/lib/ace/background_tokenizer.js b/lib/ace/background_tokenizer.js index 816719f6..5b2e76f2 100644 --- a/lib/ace/background_tokenizer.js +++ b/lib/ace/background_tokenizer.js @@ -44,8 +44,7 @@ var EventEmitter = require("./lib/event_emitter").EventEmitter; /** * class BackgroundTokenizer * - * Tokenizes items...in the background? TODO - * + * 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. * **/ @@ -148,11 +147,10 @@ var BackgroundTokenizer = function(tokenizer, editor) { }; /** - * BackgroundTokenizer.start(startRow, lastRow) -> Void + * BackgroundTokenizer.start(startRow) -> Void * - startRow (Number): The row to start at - * - lastRow (Number): The row to finish at * - * Starts tokenizing at the row indicated. TODO + * Starts tokenizing at the row indicated. * **/ diff --git a/lib/ace/edit_session.js b/lib/ace/edit_session.js index ae24b6ef..52c49463 100644 --- a/lib/ace/edit_session.js +++ b/lib/ace/edit_session.js @@ -1027,10 +1027,10 @@ var EditSession = function(text, mode) { /** * EditSession.undoChanges(deltas, dontSelect) -> Range - * - deltas (Array): - * - dontSelect (Boolean): + * - deltas (Array): An array of previous changes + * - dontSelect (Boolean): [If `true`, doesn't select the range of where the change occured]{: #dontSelect} * - * TODO + * Reverts previous changes to your document. **/ this.undoChanges = function(deltas, dontSelect) { if (!deltas.length) @@ -1060,10 +1060,10 @@ var EditSession = function(text, mode) { /** * EditSession.redoChanges(deltas, dontSelect) -> Range - * - deltas (Array): - * - dontSelect (Boolean): + * - deltas (Array): An array of previous changes + * - dontSelect (Boolean): {:dontSelect} * - * TODO + * Re-implements a previously undone change to your document. **/ this.redoChanges = function(deltas, dontSelect) { if (!deltas.length) @@ -1089,9 +1089,9 @@ var EditSession = function(text, mode) { /** * EditSession.setUndoSelect(enable) -> Void - * - enable (Boolean): + * - enable (Boolean): If `true`, selects the range of the reinserted change * - * TODO + * ENables or disables highlighting of the range where an undo occured. **/ this.setUndoSelect = function(enable) { this.$undoSelect = enable; @@ -1456,13 +1456,11 @@ var EditSession = function(text, mode) { } }; - // This should generally only be called by the renderer when a resize - // is detected. - /** + /** internal * EditSession.adjustWrapLimit(desiredLimit) -> Boolean - * - desiredLimit (Number): New limit + * - desiredLimit (Number): The new wrap limit * - * TODO + * This should generally only be called by the renderer when a resize is detected. **/ this.adjustWrapLimit = function(desiredLimit) { var wrapLimit = this.$constrainWrapLimit(desiredLimit); @@ -1707,7 +1705,7 @@ var EditSession = function(text, mode) { TAB_SPACE = 12; /** internal - * EditSession.$computeWrapSplits(tokens, wrapLimit) -> Void + * EditSession.$computeWrapSplits(tokens, wrapLimit) -> Array * * **/ @@ -1936,41 +1934,40 @@ var EditSession = function(text, mode) { return this.getRowLength(row) * config.lineHeight; } - /** related to: EditSession.documentToScreenColumn + /** internal, related to: EditSession.documentToScreenColumn * EditSession.getScreenLastRowColumn(screenRow) -> Number - * - screenRow (Number): The + * - screenRow (Number): The screen row to check * - * TODO + * Returns the column position (on screen) for the last character in the provided row. **/ this.getScreenLastRowColumn = function(screenRow) { //return this.screenToDocumentColumn(screenRow, Number.MAX_VALUE / 10) return this.documentToScreenColumn(screenRow, this.doc.getLine(screenRow).length); }; - /** + /** internal * EditSession.getDocumentLastRowColumn(docRow, docColumn) -> Number - * - * TODO + * - docRow (Number): + * - docColumn (Number): + * **/ this.getDocumentLastRowColumn = function(docRow, docColumn) { var screenRow = this.documentToScreenRow(docRow, docColumn); return this.getScreenLastRowColumn(screenRow); }; - /** + /** internal * EditSession.getDocumentLastRowColumnPosition(docRow, docColumn) -> Number * - * TODO **/ this.getDocumentLastRowColumnPosition = function(docRow, docColumn) { var screenRow = this.documentToScreenRow(docRow, docColumn); return this.screenToDocumentPosition(screenRow, Number.MAX_VALUE / 10); }; - /** + /** internal * EditSession.getRowSplitData(row) -> undefined | String - * - * TODO + * **/ this.getRowSplitData = function(row) { if (!this.$useWrapMode) { @@ -1984,35 +1981,42 @@ var EditSession = function(text, mode) { * EditSession.getScreenTabSize(screenColumn) -> Number * - screenColumn (Number): The screen column to check * - * TODO Returns the width of a tab character at `screenColumn`. + * The distance to the next tab stop at the specified screen column. **/ this.getScreenTabSize = function(screenColumn) { return this.$tabSize - screenColumn % this.$tabSize; }; - /** + /** internal * EditSession.screenToDocumentRow(screenRow, screenColumn) -> Number * - * TODO + * **/ this.screenToDocumentRow = function(screenRow, screenColumn) { return this.screenToDocumentPosition(screenRow, screenColumn).row; }; - /** + /** internal * EditSession.screenToDocumentColumn(screenRow, screenColumn) -> Number * - * TODO + * **/ this.screenToDocumentColumn = function(screenRow, screenColumn) { return this.screenToDocumentPosition(screenRow, screenColumn).column; }; - /** - * EditSession.screenToDocumentPosition(screenRow, screenColumn) -> Number + /** related to: EditSession.documentToScreenPosition + * EditSession.screenToDocumentPosition(screenRow, screenColumn) -> Object + * - screenRow (Number): The screen row to check + * - screenColumn (Number): The screen column to check * - * TODO - **/ + * 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} + * + * #### Returns + * + * The object returned has two properties: `row` and `column`. + * + **/ this.screenToDocumentPosition = function(screenRow, screenColumn) { if (screenRow < 0) { return { @@ -2114,11 +2118,19 @@ var EditSession = function(text, mode) { } }; - /** + /** related to: EditSession.screenToDocumentPosition * EditSession.documentToScreenPosition(docRow, docColumn) -> Object - * - * TODO - **/ + * - docRow (Number): The document row to check + * - docColumn (Number): The document column to check + * + * Converts document coordinates to screen coordinates. {:conversionConsiderations} + * + * #### Returns + * + * The object returned by this method has two properties: `row` and `column`. + * + * + **/ this.documentToScreenPosition = function(docRow, docColumn) { // Normalize the passed in arguments. if (typeof docColumn === "undefined") @@ -2222,19 +2234,19 @@ var EditSession = function(text, mode) { }; }; - /** + /** internal * EditSession.documentToScreenColumn(row, docColumn) -> Number * - * TODO + * **/ this.documentToScreenColumn = function(row, docColumn) { return this.documentToScreenPosition(row, docColumn).column; }; - /** + /** internal * EditSession.documentToScreenRow(docRow, docColumn) -> Number * - * TODO + * **/ this.documentToScreenRow = function(docRow, docColumn) { return this.documentToScreenPosition(docRow, docColumn).row; diff --git a/lib/ace/editor.js b/lib/ace/editor.js index 005a647d..7831b2c1 100644 --- a/lib/ace/editor.js +++ b/lib/ace/editor.js @@ -301,8 +301,7 @@ var Editor = function(renderer, session) { /** internal * Editor.$highlightBrackets() -> Void - * - * TODO + * **/ this.$highlightBrackets = function() { if (this.session.$bracketHighlight) { @@ -1217,7 +1216,7 @@ var Editor = function(renderer, session) { /** * Editor.toggleCommentLines() -> Void * - * TODO + * Given the currently selected range, this function either comments all lines or uncomments all lines (depending on whether it's commented or not). **/ this.toggleCommentLines = function() { var state = this.session.getState(this.getCursorPosition().row); @@ -1379,30 +1378,30 @@ var Editor = function(renderer, session) { }; }; - /** + /** internal * Editor@onCompositionStart(text) * - text (String): The text being written * - * TODO + * **/ this.onCompositionStart = function(text) { this.renderer.showComposition(this.getCursorPosition()); }; - /** + /** internal * Editor@onCompositionUpdate(text) * - text (String): The text being written * - * TODO + * **/ this.onCompositionUpdate = function(text) { this.renderer.setCompositionText(text); }; - /** + /** internal * Editor@onCompositionEnd() * - * TODO + * **/ this.onCompositionEnd = function() { this.renderer.hideComposition(); @@ -1430,7 +1429,7 @@ var Editor = function(renderer, session) { * Editor.isRowVisible(row) -> Boolean * - row (Number): The row to check * - * TODO Indicates if the row is currently visible. + * Indicates if the row is currently visible on the screen. **/ this.isRowVisible = function(row) { return (row >= this.getFirstVisibleRow() && row <= this.getLastVisibleRow()); @@ -1440,7 +1439,7 @@ var Editor = function(renderer, session) { * Editor.isRowFullyVisible(row) -> Boolean * - row (Number): The row to check * - * TODO Indicates if the row is currently visible. + * Indicates if the entire row is currently visible on the screen. **/ this.isRowFullyVisible = function(row) { return (row >= this.renderer.getFirstFullyVisibleRow() && row <= this.renderer.getLastFullyVisibleRow()); @@ -1469,7 +1468,7 @@ var Editor = function(renderer, session) { /** * Editor.selectPageDown() -> Void * - * TODO + * Selects the text from the current position of the document until where a "page down" finishes. **/ this.selectPageDown = function() { var row = this.$getPageDownRow() + Math.floor(this.$getVisibleRowCount() / 2); @@ -1485,7 +1484,7 @@ var Editor = function(renderer, session) { /** * Editor.selectPageUp() -> Void * - * TODO + * Selects the text from the current position of the document until where a "page up" finishes. **/ this.selectPageUp = function() { var visibleRows = this.renderer.getScrollTopRow() - this.renderer.getScrollBottomRow(); @@ -1502,7 +1501,7 @@ var Editor = function(renderer, session) { /** * Editor.gotoPageDown() -> Void * - * TODO + * Shifts the document to wherever "page down" is, as well as moving the cursor position. **/ this.gotoPageDown = function() { var row = this.$getPageDownRow(); @@ -1515,7 +1514,7 @@ var Editor = function(renderer, session) { /** * Editor.gotoPageUp() -> Void * - * TODO + * Shifts the document to wherever "page up" is, as well as moving the cursor position. **/ this.gotoPageUp = function() { var row = this.$getPageUpRow(); @@ -1528,7 +1527,7 @@ var Editor = function(renderer, session) { /** * Editor.scrollPageDown() -> Void * - * TODO + * Scrolls the document to wherever "page down" is, without changing the cursor position. **/ this.scrollPageDown = function() { this.scrollToRow(this.$getPageDownRow()); @@ -1537,7 +1536,7 @@ var Editor = function(renderer, session) { /** * Editor.scrollPageUp() -> Void * - * TODO + * Scrolls the document to wherever "page up" is, without changing the cursor position. **/ this.scrollPageUp = function() { this.renderer.scrollToRow(this.$getPageUpRow()); @@ -1556,10 +1555,10 @@ var Editor = function(renderer, session) { /** related to: VirtualRenderer.scrollToLine * Editor.scrollToLine(line, center) -> Void - * - line (Number): - * - center (Boolean): + * - line (Number): The line to scroll to + * - center (Boolean): If `true` * - * TODO + * TODO scrollsa to line, if center == true, puts line in middle of screen or attempts to) **/ this.scrollToLine = function(line, center) { this.renderer.scrollToLine(line, center); @@ -1568,7 +1567,7 @@ var Editor = function(renderer, session) { /** * Editor.centerSelection() -> Void * - * Moves the current cursor selection to the center of the line. + * Attempts to center the current selection on the screen. **/ this.centerSelection = function() { var range = this.getSelectionRange(); @@ -1595,7 +1594,7 @@ var Editor = function(renderer, session) { /** related to: EditSession.documentToScreenPosition * Editor.getCursorPositionScreen() -> Number * - * TODO + * Returns the screen position of the cursor. **/ this.getCursorPositionScreen = function() { return this.session.documentToScreenPosition(this.getCursorPosition()); @@ -1836,8 +1835,10 @@ var Editor = function(renderer, session) { /** * Editor.replace(replacement, options) -> Void - * - * TODO + * - replacement (String): The text to replace with + * - options (Object): The [[Search `Search`]] options to use + * + * Replaces the first occurance of `options.needle` with the value in `replacement`. **/ this.replace = function(replacement, options) { if (options) @@ -1854,8 +1855,10 @@ var Editor = function(renderer, session) { /** * Editor.replaceAll(replacement, options) -> Void - * - * TODO + * - replacement (String): The text to replace with + * - options (Object): The [[Search `Search`]] options to use + * + * Replaces all occurances of `options.needle` with the value in `replacement`. **/ this.replaceAll = function(replacement, options) { if (options) { @@ -1971,10 +1974,10 @@ var Editor = function(renderer, session) { this.session.getUndoManager().redo(); }; - /** + /** * Editor.destroy() -> Void * - * TODO + * Cleans up the entire editor. **/ this.destroy = function() { this.renderer.destroy(); diff --git a/lib/ace/placeholder.js b/lib/ace/placeholder.js index d9fc224a..df1358f4 100644 --- a/lib/ace/placeholder.js +++ b/lib/ace/placeholder.js @@ -139,7 +139,7 @@ var PlaceHolder = function(session, length, pos, others, mainClass, othersClass) /** * PlaceHolder.hideOtherMarkers() -> Void * - * TODO + * Hides all over markers in the [[EditSesssion `EditSession`]] that are not the currently selected one. * **/ this.hideOtherMarkers = function() { diff --git a/lib/ace/range.js b/lib/ace/range.js index d4a57fbc..a74810a5 100644 --- a/lib/ace/range.js +++ b/lib/ace/range.js @@ -446,7 +446,7 @@ var Range = function(startRow, startColumn, endRow, endColumn) { * - firstRow (Number): The starting row * - lastRow (Number): The ending row * - * TODO + * Returns the part of the current `Range` that occurs within the boundaries of `firstRow` and `lastRow` as a new `Range` object. * **/ this.clipRows = function(firstRow, lastRow) { @@ -545,10 +545,10 @@ var Range = function(startRow, startColumn, endRow, endColumn) { }; /** - * Range.toScreenRange() -> Range - * - * TODO - * + * Range.toScreenRange(session) -> Range + * - session (EditSession): The `EditSession` to retrieve coordinates from + * + * Given the current `Range`, this function converts those starting and ending points into screen positions, and then returns a new `Range` object. **/ this.toScreenRange = function(session) { var screenPosStart = diff --git a/lib/ace/renderloop.js b/lib/ace/renderloop.js index c5701393..ff88790a 100644 --- a/lib/ace/renderloop.js +++ b/lib/ace/renderloop.js @@ -41,17 +41,17 @@ define(function(require, exports, module) { var event = require("./lib/event"); -/** +/** internal * class RenderLoop * - * TODO + * Batches changes (that force something to be redrawn) in the background. * **/ -/** +/** internal * new RenderLoop(onRender, win) * - * TODO + * * **/ var RenderLoop = function(onRender, win) { @@ -63,11 +63,11 @@ var RenderLoop = function(onRender, win) { (function() { - /** + /** internal * RenderLoop.schedule(change) -> Void * - change (Array): * - * TODO + * **/ this.schedule = function(change) { //this.onRender(change); diff --git a/lib/ace/selection.js b/lib/ace/selection.js index b6011098..2b52dc35 100644 --- a/lib/ace/selection.js +++ b/lib/ace/selection.js @@ -162,7 +162,7 @@ var Selection = function(session) { * Selection.shiftSelection(columns) -> Void * - columns (Number): The number of columns to shift by * - * TODO + * Shifts the selection up (or down, if [[Selection.isBackwards `isBackwards()`]] is true) the given number of columns. * **/ this.shiftSelection = function(columns) { @@ -703,9 +703,9 @@ var Selection = function(session) { * Selection.moveCursorTo(row, column, preventUpdateDesiredColumn) -> Void * - row (Number): The row to move to * - column (Number): The column to move to - * - preventUpdateDesiredColumn (Boolean): Indicates if the column should be updated (`true`) or not (`false`) + * - preventUpdateDesiredColumn (Boolean): [If `true`, the cursor move does not respect the previous column]{: #preventUpdateBool} * - * TODO + * Moves the cursor to the row and column provided. [If `preventUpdateDesiredColumn` is `true`, then the cursor stays in the same column position as its original point.]{: #preventUpdateBoolDesc} **/ this.moveCursorTo = function(row, column, preventUpdateDesiredColumn) { // Ensure the row/column is not inside of a fold. @@ -727,9 +727,9 @@ var Selection = function(session) { * Selection.moveCursorToScreen(row, column, preventUpdateDesiredColumn) -> Void * - row (Number): The row to move to * - column (Number): The column to move to - * - preventUpdateDesiredColumn (Boolean): Indicates if the column should be updated (`true`) or not (`false`) + * - preventUpdateDesiredColumn (Boolean): {:preventUpdateBool} * - * TODO + * Moves the cursor to the screen position indicated by row and column. {:preventUpdateBoolDesc} **/ this.moveCursorToScreen = function(row, column, preventUpdateDesiredColumn) { var pos = this.session.screenToDocumentPosition(row, column); diff --git a/lib/ace/split.js b/lib/ace/split.js index dfe4f3be..13c7ef1a 100644 --- a/lib/ace/split.js +++ b/lib/ace/split.js @@ -47,20 +47,20 @@ var Editor = require("./editor").Editor; var Renderer = require("./virtual_renderer").VirtualRenderer; var EditSession = require("./edit_session").EditSession; -/** +/** internal * class Split * - * TODO + * * **/ -/** +/** internal * new Split(container, theme, splits) - * - container (Document): The document to associate with the anchor - * - theme (Number): The starting row position - * - splits (Number): The starting column position + * - container (Document): The document to associate with the split + * - theme (String): The name of the initial theme + * - splits (Number): The number of initial splits + * * - * TODO * **/ @@ -104,11 +104,11 @@ var Split = function(container, theme, splits) { return editor; }; - /** + /** internal * Split.setSplits(splits) -> Void * - splits (Number): The new number of splits * - * TODO + * * **/ this.setSplits = function(splits) { @@ -193,7 +193,7 @@ var Split = function(container, theme, splits) { /** related to: Editor.setTheme * Split.setTheme(theme) -> Void - * - theme (String): + * - theme (String): The name of the theme to set * * Sets a theme for each of the available editors. **/ @@ -203,11 +203,11 @@ var Split = function(container, theme, splits) { }); }; - /** + /** internal * Split.setKeyboardHandler(keybinding) -> Void * - keybinding (String): * - * TODO + * **/ this.setKeyboardHandler = function(keybinding) { this.$editors.forEach(function(editor) { @@ -215,12 +215,12 @@ var Split = function(container, theme, splits) { }); }; - /** + /** internal * Split.forEach(callback, scope) -> Void * - callback (Function): A callback function to execute - * - scope (String): TODO + * - scope (String): * - * Executes `callback` on all of the available editors. TODO + * Executes `callback` on all of the available editors. * **/ this.forEach = function(callback, scope) { @@ -303,21 +303,21 @@ var Split = function(container, theme, splits) { return session; }; - /** + /** internal * Split.getOriantation() -> Number * - * Returns the orientation. TODO + * Returns the orientation. * **/ this.getOriantation = function() { return this.$oriantation; }; - /** + /** internal * Split.setOriantation(oriantation) -> Void * - oriantation (Number): * - * Sets the orientation. TODO + * Sets the orientation. * **/ this.setOriantation = function(oriantation) { @@ -328,10 +328,10 @@ var Split = function(container, theme, splits) { this.resize(); }; - /** + /** internal * Split.resize() -> Void * - * TODO + * * **/ this.resize = function() { @@ -364,10 +364,10 @@ var Split = function(container, theme, splits) { }).call(Split.prototype); - /** + /** internal * Split.UndoManagerProxy() -> Void * - * TODO + * * **/ function UndoManagerProxy(undoManager, session) { diff --git a/lib/ace/token_iterator.js b/lib/ace/token_iterator.js index 027d8c5c..5cfc6f08 100644 --- a/lib/ace/token_iterator.js +++ b/lib/ace/token_iterator.js @@ -42,7 +42,7 @@ define(function(require, exports, module) { /** * class TokenIterator * - * This class handles all sorts of token iterizing. Is that even a word? TODO + * This class provides an essay way to treat the document as a stream of tokens, and provides methods to iterate over these tokens. * **/ @@ -52,7 +52,7 @@ define(function(require, exports, module) { * - initialRow (Number): The row to start the tokenizing at * - initialColumn (Number): The column to start the tokenizing at * - * Creates a new token iterator object. The inital token index is set to the row and column coordinates. + * Creates a new token iterator object. The inital token index is set to the provided row and column coordinates. * **/ var TokenIterator = function(session, initialRow, initialColumn) { diff --git a/lib/ace/tokenizer.js b/lib/ace/tokenizer.js index 127d965c..6cc52b72 100644 --- a/lib/ace/tokenizer.js +++ b/lib/ace/tokenizer.js @@ -41,16 +41,16 @@ define(function(require, exports, module) { /** * class Tokenizer * - * This object handles all sorts of tokenizing? TODO + * This class takes a set of highlighting rules, and creates a tokenizer out of them. For more information, see [the wiki on extending highlighters](https://github.com/ajaxorg/ace/wiki/Creating-or-Extending-an-Edit-Mode#wiki-extendingTheHighlighter). * **/ /** * new Tokenizer(rules, flag) - * - rules (String): - * - flag (String): + * - rules (Object): The highlighting rules + * - flag (String): Any additional regular expression flags to pass (like "i" for case insensitive) * - * TODO + * Constructs a new tokenizer based on the given rules and flags. * **/ var Tokenizer = function(rules, flag) { @@ -94,7 +94,7 @@ var Tokenizer = function(rules, flag) { /** * Tokenizer.getLineTokens() -> Object * - * TODO. Returns an object containing two properties: `tokens`, which contains all the tokens; and `state`, the current state. + * 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/undomanager.js b/lib/ace/undomanager.js index c457cf94..d53979bd 100644 --- a/lib/ace/undomanager.js +++ b/lib/ace/undomanager.js @@ -43,7 +43,7 @@ define(function(require, exports, module) { /** * class UndoManager * - * This object controls all the undoing that needs to be done. TODO + * This object maintains the undo stack for an [[EditSession `EditSession`]]. * **/ @@ -60,9 +60,12 @@ var UndoManager = function() { /** * UndoManager.execute(options) -> Void - * - options (Object): + * - options (Object): Contains additional properties + * + * Provides a means for implementing your own undo manager. `options` has one property, `args`, an [[Array `Array`]], with two elements: + * * `args[0]` is an array of deltas + * * `args[1]` is the document to associate with * - * TODO **/ this.execute = function(options) { var deltas = options.args[0]; @@ -73,7 +76,7 @@ var UndoManager = function() { /** * UndoManager.undo(dontSelect) -> Range - * - dontSelect (Boolean): TODO + * - dontSelect (Boolean): {:dontSelect} * * [Perform an undo operation on the document, reverting the last change. Returns the range of the undo.]{: #UndoManager.undo} **/ @@ -90,7 +93,7 @@ var UndoManager = function() { /** * UndoManager.redo(dontSelect) -> Void - * - dontSelect (Boolean): TODO + * - dontSelect (Boolean): {:dontSelect} * * [Perform a redo operation on the document, reimplementing the last change.]{: #UndoManager.redo} **/ diff --git a/lib/ace/virtual_renderer.js b/lib/ace/virtual_renderer.js index 8304bc7c..5cfac10a 100644 --- a/lib/ace/virtual_renderer.js +++ b/lib/ace/virtual_renderer.js @@ -59,16 +59,16 @@ dom.importCssString(editorCss, "ace_editor"); /** * class VirtualRenderer * - * TODO + * The class that is responsible for drawing everything you see on the screen! * **/ /** * new VirtualRenderer(container, theme) - * - container (Editor): + * - container (DOMElement): The root element of the editor * - theme (String): The starting theme * - * TODO + * Constructs a new `VirtualRenderer` within the `container` specified, applying the given `theme`. * **/ @@ -265,7 +265,7 @@ var VirtualRenderer = function(container, theme) { /** * VirtualRenderer.onResize(force) -> Void - * - force (Boolean): TODO + * - force (Boolean): If `true`, recomputes the size, even if the height and width haven't changed * * [Triggers a resize of the editor.]{: #VirtualRenderer.onResize} **/ @@ -306,7 +306,7 @@ var VirtualRenderer = function(container, theme) { /** * VirtualRenderer.adjustWrapLimit() -> Void * - * Adjusts the wrap limits. TODO. + * Adjusts the wrap limit, which is the number of characters that can fit within the width of the edit area on screen. **/ this.adjustWrapLimit = function() { var availableWidth = this.$size.scrollerWidth - this.$padding * 2; @@ -425,27 +425,27 @@ var VirtualRenderer = function(container, theme) { }; /** - * VirtualRenderer.getContainerElement() -> TODO + * VirtualRenderer.getContainerElement() -> DOMElement * - * TODO + * Returns the root element containing this renderer. **/ this.getContainerElement = function() { return this.container; }; /** - * VirtualRenderer.getMouseEventTarget() -> TODO + * VirtualRenderer.getMouseEventTarget() -> DOMElement * - * TODO + * Returns the element that the mouse events are attached to **/ this.getMouseEventTarget = function() { return this.content; }; /** - * VirtualRenderer.getTextAreaContainer() -> TODO + * VirtualRenderer.getTextAreaContainer() -> DOMElement * - * TODO + * Returns the element to which the hidden text area is added. **/ this.getTextAreaContainer = function() { return this.container; @@ -489,7 +489,7 @@ var VirtualRenderer = function(container, theme) { /** * VirtualRenderer.getFirstFullyVisibleRow() -> Number * - * Returns the index of the first fully visible row. "Fully" here means TODO + * Returns the index of the first fully visible row. "Fully" here means that the characters in the row are not truncated; that the top and the bottom of the row are on the screen. **/ this.getFirstFullyVisibleRow = function() { return this.layerConfig.firstRow + (this.layerConfig.offset === 0 ? 0 : 1); @@ -498,7 +498,7 @@ var VirtualRenderer = function(container, theme) { /** * VirtualRenderer.getLastFullyVisibleRow() -> Number * - * Returns the index of the last fully visible row. "Fully" here means TODO + * Returns the index of the last fully visible row. "Fully" here means that the characters in the row are not truncated; that the top and the bottom of the row are on the screen. **/ this.getLastFullyVisibleRow = function() { var flint = Math.floor((this.layerConfig.height + this.layerConfig.offset) / this.layerConfig.lineHeight); @@ -757,7 +757,7 @@ var VirtualRenderer = function(container, theme) { /** * VirtualRenderer.updateFrontMarkers() -> Void * - * TODO + * Schedules an update to all the front markers in the document. **/ this.updateFrontMarkers = function() { this.$markerFront.setMarkers(this.session.getMarkers(true)); @@ -767,7 +767,7 @@ var VirtualRenderer = function(container, theme) { /** * VirtualRenderer.updateBackMarkers() -> Void * - * TODO + * Schedules an update to all the back markers in the document. **/ this.updateBackMarkers = function() { this.$markerBack.setMarkers(this.session.getMarkers()); @@ -848,9 +848,9 @@ var VirtualRenderer = function(container, theme) { }; /** - * VirtualRenderer.scrollCursorIntoView() -> VOid + * VirtualRenderer.scrollCursorIntoView() -> Void * - * TODO + * Scrolls the cursor into the first visibile area of the editor **/ this.scrollCursorIntoView = function() { // the editor is not visible @@ -904,7 +904,7 @@ var VirtualRenderer = function(container, theme) { /** * VirtualRenderer.getScrollTopRow() -> Number * - * Returns the size of the first row, in pixels. TODO + * Returns the first visible row, regardless of whether it's fully visible or not. **/ this.getScrollTopRow = function() { return this.scrollTop / this.lineHeight; @@ -913,7 +913,7 @@ var VirtualRenderer = function(container, theme) { /** * VirtualRenderer.getScrollBottomRow() -> Number * - * Returns the size of the last row, in pixels. + * Returns the last visible row, regardless of whether it's fully visible or not. **/ this.getScrollBottomRow = function() { return Math.max(0, Math.floor((this.scrollTop + this.$size.scrollerHeight) / this.lineHeight) - 1); @@ -1006,9 +1006,16 @@ var VirtualRenderer = function(container, theme) { }; /** - * VirtualRenderer.screenToTextCoordinates(pageX, pageY) -> Number + * VirtualRenderer.screenToTextCoordinates(pageX, pageY) -> Object + * - pageX (Number): The x-coordinate relative to the left edge of the document + * - pageY (Number): The y-coordinate relative to the top edge of the document + * + * Returns the document position, based on the coordinates provided. + * + * #### Returns + * + * The object returned has two properties: `row` and `column`. * - * TODO **/ this.screenToTextCoordinates = function(pageX, pageY) { var canvasPos = this.scroller.getBoundingClientRect(); @@ -1025,8 +1032,15 @@ var VirtualRenderer = function(container, theme) { /** * VirtualRenderer.textToScreenCoordinates(row, column) -> Object + * - row (Number): The document row position + * - column (Number): The document column position + * + * Returns an object containing the `pageX` and `pageY` coordinates of the document position. + * + * #### Returns + * + * The object returned has two properties: `pageX` and `pageY`. * - * TODO **/ this.textToScreenCoordinates = function(row, column) { var canvasPos = this.scroller.getBoundingClientRect(); @@ -1059,10 +1073,10 @@ var VirtualRenderer = function(container, theme) { dom.removeCssClass(this.container, "ace_focus"); }; - /** + /** internal * VirtualRenderer.showComposition(position) -> Void + * - position (Number): * - * TODO **/ this.showComposition = function(position) { if (!this.$composition) {