From 6e1bcd06f95b65d4495179ffcef4ef6189f53f5b Mon Sep 17 00:00:00 2001 From: abose Date: Thu, 5 Mar 2026 19:34:20 +0530 Subject: [PATCH] fix: more docs build break --- docs/API-Reference/document/Document.md | 60 +++++++++++++++++-------- src/document/Document.js | 43 +++++++++++------- 2 files changed, 69 insertions(+), 34 deletions(-) diff --git a/docs/API-Reference/document/Document.md b/docs/API-Reference/document/Document.md index 21679b25d5..1c1ef799c3 100644 --- a/docs/API-Reference/document/Document.md +++ b/docs/API-Reference/document/Document.md @@ -27,11 +27,11 @@ const Document = brackets.getModule("document/Document") * [.replaceRange(text, start, end, origin)](#Document+replaceRange) * [.getRange(start, end)](#Document+getRange) ⇒ string * [.getLine(Zero-based)](#Document+getLine) ⇒ string - * [.posFromIndex(index)](#Document+posFromIndex) ⇒ Object + * [.posFromIndex(index)](#Document+posFromIndex) ⇒ [TextPosition](#TextPosition) * [.batchOperation(doOperation)](#Document+batchOperation) * [.notifySaved()](#Document+notifySaved) - * [.adjustPosForChange(pos, textLines, start, end)](#Document+adjustPosForChange) ⇒ Object - * [.doMultipleEdits(edits, origin)](#Document+doMultipleEdits) ⇒ Object + * [.adjustPosForChange(pos, textLines, start, end)](#Document+adjustPosForChange) ⇒ [TextPosition](#TextPosition) + * [.doMultipleEdits(edits, origin)](#Document+doMultipleEdits) ⇒ [Array.<SelectionRange>](#SelectionRange) * [.getLanguage()](#Document+getLanguage) ⇒ Language * [.isUntitled()](#Document+isUntitled) ⇒ boolean * [.reload()](#Document+reload) ⇒ promise @@ -48,7 +48,7 @@ Document dispatches these events: __change__ -- When the text of the editor changes (including due to undo/redo). -Passes ({'Document'}, {'ChangeList'}), where ChangeList is an array +Passes (`Document`, `ChangeList`), where ChangeList is an array of change record objects. Each change record looks like: ```js { from: start of change, expressed as {line: , ch: }, @@ -214,8 +214,8 @@ fixed when we migrate to use CodeMirror's native document-linking functionality. | Param | Type | Description | | --- | --- | --- | | text | string | Text to insert or replace the range with | -| start | Object | Start of range, inclusive (if 'to' specified) or insertion point (if not) | -| end | Object | End of range, exclusive; optional | +| start | [TextPosition](#TextPosition) | Start of range, inclusive (if 'to' specified) or insertion point (if not) | +| end | [TextPosition](#TextPosition) | End of range, exclusive; optional | | origin | string | Optional string used to batch consecutive edits for undo. If origin starts with "+", then consecutive edits with the same origin will be batched for undo if they are close enough together in time. If origin starts with "*", then all consecutive edit with the same origin will be batched for undo. Edits with origins starting with other characters will not be batched. (Note that this is a higher level of batching than batchOperation(), which already batches all edits within it for undo. Origin batching works across operations.) | @@ -227,8 +227,8 @@ Returns the characters in the given range. Line endings are normalized to '\n'. | Param | Type | Description | | --- | --- | --- | -| start | Object | Start of range, inclusive | -| end | Object | End of range, exclusive | +| start | [TextPosition](#TextPosition) | Start of range, inclusive | +| end | [TextPosition](#TextPosition) | End of range, exclusive | @@ -243,9 +243,9 @@ Returns the text of the given line (excluding any line ending characters) -### document.posFromIndex(index) ⇒ Object +### document.posFromIndex(index) ⇒ [TextPosition](#TextPosition) Given a character index within the document text (assuming \n newlines), -returns the corresponding {line, ch} position. Works whether or not +returns the corresponding `{line, ch}` position. Works whether or not a master editor is attached. **Kind**: instance method of [Document](#Document) @@ -275,7 +275,7 @@ document not dirty and notifies listeners of the save. **Kind**: instance method of [Document](#Document) -### document.adjustPosForChange(pos, textLines, start, end) ⇒ Object +### document.adjustPosForChange(pos, textLines, start, end) ⇒ [TextPosition](#TextPosition) Adjusts a given position taking a given replaceRange-type edit into account. If the position is within the original edit range (start and end inclusive), it gets pushed to the end of the content that replaced the range. Otherwise, @@ -283,18 +283,18 @@ if it's after the edit, it gets adjusted so it refers to the same character it did before the edit. **Kind**: instance method of [Document](#Document) -**Returns**: Object - The adjusted position. +**Returns**: [TextPosition](#TextPosition) - The adjusted position. | Param | Type | Description | | --- | --- | --- | -| pos | Object | The position to adjust. | +| pos | [TextPosition](#TextPosition) | The position to adjust. | | textLines | Array.<string> | The text of the change, split into an array of lines. | -| start | Object | The start of the edit. | -| end | Object | The end of the edit. | +| start | [TextPosition](#TextPosition) | The start of the edit. | +| end | [TextPosition](#TextPosition) | The end of the edit. | -### document.doMultipleEdits(edits, origin) ⇒ Object +### document.doMultipleEdits(edits, origin) ⇒ [Array.<SelectionRange>](#SelectionRange) Helper function for edit operations that operate on multiple selections. Takes an "edit list" that specifies a list of replaceRanges that should occur, but where all the positions are with respect to the document state before all the edits (i.e., you don't have to figure out how to fix @@ -312,11 +312,11 @@ then this function will adjust them as necessary for the effects of other edits, flat list of all the selections, suitable for passing to `setSelections()`. **Kind**: instance method of [Document](#Document) -**Returns**: Object - The list of passed selections adjusted for the performed edits, if any. +**Returns**: [Array.<SelectionRange>](#SelectionRange) - The list of passed selections adjusted for the performed edits, if any. | Param | Type | Description | | --- | --- | --- | -| edits | Object | Specifies the list of edits to perform in a manner similar to CodeMirror's `replaceRange`. This array will be mutated. `edit` is the edit to perform: `text` will replace the current contents of the range between `start` and `end`. If `end` is unspecified, the text is inserted at `start`. `start` and `end` should be positions relative to the document *ignoring* all other edit descriptions (i.e., as if you were only performing this one edit on the document). If any of the edits overlap, an error will be thrown. If `selection` is specified, it should be a selection associated with this edit. If `isBeforeEdit` is set on the selection, the selection will be fixed up for this edit. If not, it won't be fixed up for this edit, meaning it should be expressed in terms of the document state after this individual edit is performed (ignoring any other edits). Note that if you were planning on just specifying `isBeforeEdit` for every selection, you can accomplish the same thing by simply not passing any selections and letting the editor update the existing selections automatically. Note that `edit` and `selection` can each be either an individual edit/selection, or a group of edits/selections to apply in order. This can be useful if you need to perform multiple edits in a row and then specify a resulting selection that shouldn't be fixed up for any of those edits (but should be fixed up for edits related to other selections). It can also be useful if you have several selections that should ignore the effects of a given edit because you've fixed them up already (this commonly happens with line-oriented edits where multiple cursors on the same line should be ignored, but still tracked). Within an edit group, edit positions must be specified relative to previous edits within that group. Also, the total bounds of edit groups must not overlap (e.g. edits in one group can't surround an edit from another group). | +| edits | Array.<Object> | Specifies the list of edits to perform in a manner similar to CodeMirror's `replaceRange`. This array will be mutated. `edit` is the edit to perform: `text` will replace the current contents of the range between `start` and `end`. If `end` is unspecified, the text is inserted at `start`. `start` and `end` should be positions relative to the document *ignoring* all other edit descriptions (i.e., as if you were only performing this one edit on the document). If any of the edits overlap, an error will be thrown. If `selection` is specified, it should be a selection associated with this edit. If `isBeforeEdit` is set on the selection, the selection will be fixed up for this edit. If not, it won't be fixed up for this edit, meaning it should be expressed in terms of the document state after this individual edit is performed (ignoring any other edits). Note that if you were planning on just specifying `isBeforeEdit` for every selection, you can accomplish the same thing by simply not passing any selections and letting the editor update the existing selections automatically. Note that `edit` and `selection` can each be either an individual edit/selection, or a group of edits/selections to apply in order. This can be useful if you need to perform multiple edits in a row and then specify a resulting selection that shouldn't be fixed up for any of those edits (but should be fixed up for edits related to other selections). It can also be useful if you have several selections that should ignore the effects of a given edit because you've fixed them up already (this commonly happens with line-oriented edits where multiple cursors on the same line should be ignored, but still tracked). Within an edit group, edit positions must be specified relative to previous edits within that group. Also, the total bounds of edit groups must not overlap (e.g. edits in one group can't surround an edit from another group). | | origin | string | An optional edit origin that's passed through to each replaceRange(). | @@ -347,3 +347,27 @@ Reloads the document from FileSystem Normalizes line endings the same way CodeMirror would **Kind**: static method of [Document](#Document) + + +## TextPosition : Object +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| line | number | Zero-based line number | +| ch | number | Zero-based character offset | + + + +## SelectionRange : Object +**Kind**: global typedef +**Properties** + +| Name | Type | Description | +| --- | --- | --- | +| start | [TextPosition](#TextPosition) | Start of the selection | +| end | [TextPosition](#TextPosition) | End of the selection | +| primary | boolean | Whether this is the primary selection | +| reversed | boolean | Whether the selection is reversed | + diff --git a/src/document/Document.js b/src/document/Document.js index 5d1de3fe13..43a81d97bf 100644 --- a/src/document/Document.js +++ b/src/document/Document.js @@ -33,6 +33,20 @@ define(function (require, exports, module) { CodeMirror = require("thirdparty/CodeMirror/lib/codemirror"), _ = require("thirdparty/lodash"); + /** + * @typedef {Object} TextPosition + * @property {number} line - Zero-based line number + * @property {number} ch - Zero-based character offset + */ + + /** + * @typedef {Object} SelectionRange + * @property {TextPosition} start - Start of the selection + * @property {TextPosition} end - End of the selection + * @property {boolean} primary - Whether this is the primary selection + * @property {boolean} reversed - Whether the selection is reversed + */ + /** * Model for the contents of a single file and its current modification state. * See DocumentManager documentation for important usage notes. @@ -41,7 +55,7 @@ define(function (require, exports, module) { * * __change__ -- When the text of the editor changes (including due to undo/redo). * - * Passes ({'Document'}, {'ChangeList'}), where ChangeList is an array + * Passes (`Document`, `ChangeList`), where ChangeList is an array * of change record objects. Each change record looks like: *```js * { from: start of change, expressed as {line: , ch: }, @@ -454,8 +468,8 @@ define(function (require, exports, module) { * fixed when we migrate to use CodeMirror's native document-linking functionality. * * @param {!string} text Text to insert or replace the range with - * @param {!{line:number, ch:number}} start Start of range, inclusive (if 'to' specified) or insertion point (if not) - * @param {?{line:number, ch:number}} end End of range, exclusive; optional + * @param {!TextPosition} start Start of range, inclusive (if 'to' specified) or insertion point (if not) + * @param {?TextPosition} end End of range, exclusive; optional * @param {?string} origin Optional string used to batch consecutive edits for undo. * If origin starts with "+", then consecutive edits with the same origin will be batched for undo if * they are close enough together in time. @@ -473,8 +487,8 @@ define(function (require, exports, module) { /** * Returns the characters in the given range. Line endings are normalized to '\n'. - * @param {!{line:number, ch:number}} start Start of range, inclusive - * @param {!{line:number, ch:number}} end End of range, exclusive + * @param {!TextPosition} start Start of range, inclusive + * @param {!TextPosition} end End of range, exclusive * @return {!string} */ Document.prototype.getRange = function (start, end) { @@ -494,10 +508,10 @@ define(function (require, exports, module) { /** * Given a character index within the document text (assuming \n newlines), - * returns the corresponding {line, ch} position. Works whether or not + * returns the corresponding `{line, ch}` position. Works whether or not * a master editor is attached. * @param {number} index - Zero-based character offset - * @return {{line: number, ch: number}} + * @return {TextPosition} */ Document.prototype.posFromIndex = function (index) { if (this._masterEditor) { @@ -607,11 +621,11 @@ define(function (require, exports, module) { * it gets pushed to the end of the content that replaced the range. Otherwise, * if it's after the edit, it gets adjusted so it refers to the same character * it did before the edit. - * @param {!{line:number, ch: number}} pos The position to adjust. + * @param {!TextPosition} pos The position to adjust. * @param {!Array.} textLines The text of the change, split into an array of lines. - * @param {!{line: number, ch: number}} start The start of the edit. - * @param {!{line: number, ch: number}} end The end of the edit. - * @return {{line: number, ch: number}} The adjusted position. + * @param {!TextPosition} start The start of the edit. + * @param {!TextPosition} end The end of the edit. + * @return {TextPosition} The adjusted position. */ Document.prototype.adjustPosForChange = function (pos, textLines, start, end) { // Same as CodeMirror.adjustForChange(), but that's a private function @@ -662,10 +676,7 @@ define(function (require, exports, module) { * then this function will adjust them as necessary for the effects of other edits, and then return a * flat list of all the selections, suitable for passing to `setSelections()`. * - * @param {!{edit: {text: string, start:{line: number, ch: number}, end: {line: number, ch: number} | undefined} - * | {text: string, start:{line: number, ch: number}, end: {line: number, ch: number} | undefined}, - * selection: {start:{line:number, ch:number}, end:{line:number, ch:number}, - * primary:boolean, reversed: boolean, isBeforeEdit: boolean} | undefined}} edits + * @param {!Array.} edits * Specifies the list of edits to perform in a manner similar to CodeMirror's `replaceRange`. This array * will be mutated. * @@ -694,7 +705,7 @@ define(function (require, exports, module) { * the total bounds of edit groups must not overlap (e.g. edits in one group can't surround an edit from another group). * * @param {?string} origin An optional edit origin that's passed through to each replaceRange(). - * @return {{start:{line:number, ch:number}, end:{line:number, ch:number}, primary:boolean, reversed: boolean[]}} + * @return {Array.} * The list of passed selections adjusted for the performed edits, if any. */