Skip to content

fix: more docs build break #2725

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
abose merged 1 commit into from
Mar 5, 2026
+69 −34
Merged

fix: more docs build break #2725

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 42 additions & 18 deletions docs/API-Reference/document/Document.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,11 +27,11 @@ const Document = brackets.getModule("document/Document")
* [.replaceRange(text, start, end, origin)](#Document+replaceRange)
* [.getRange(start, end)](#Document+getRange) ⇒ <code>string</code>
* [.getLine(Zero-based)](#Document+getLine) ⇒ <code>string</code>
* [.posFromIndex(index)](#Document+posFromIndex) ⇒ <code>Object</code>
* [.posFromIndex(index)](#Document+posFromIndex) ⇒ [<code>TextPosition</code>](#TextPosition)
* [.batchOperation(doOperation)](#Document+batchOperation)
* [.notifySaved()](#Document+notifySaved)
* [.adjustPosForChange(pos, textLines, start, end)](#Document+adjustPosForChange) ⇒ <code>Object</code>
* [.doMultipleEdits(edits, origin)](#Document+doMultipleEdits) ⇒ <code>Object</code>
* [.adjustPosForChange(pos, textLines, start, end)](#Document+adjustPosForChange) ⇒ [<code>TextPosition</code>](#TextPosition)
* [.doMultipleEdits(edits, origin)](#Document+doMultipleEdits) ⇒ [<code>Array.&lt;SelectionRange&gt;</code>](#SelectionRange)
* [.getLanguage()](#Document+getLanguage) ⇒ <code>Language</code>
* [.isUntitled()](#Document+isUntitled) ⇒ <code>boolean</code>
* [.reload()](#Document+reload) ⇒ <code>promise</code>
Expand All @@ -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: <line number>, ch: <character offset>},
Expand Down Expand Up @@ -214,8 +214,8 @@ fixed when we migrate to use CodeMirror's native document-linking functionality.
| Param | Type | Description |
| --- | --- | --- |
| text | <code>string</code> | Text to insert or replace the range with |
| start | <code>Object</code> | Start of range, inclusive (if 'to' specified) or insertion point (if not) |
| end | <code>Object</code> | End of range, exclusive; optional |
| start | [<code>TextPosition</code>](#TextPosition) | Start of range, inclusive (if 'to' specified) or insertion point (if not) |
| end | [<code>TextPosition</code>](#TextPosition) | End of range, exclusive; optional |
| origin | <code>string</code> | 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.) |

<a name="Document+getRange"></a>
Expand All @@ -227,8 +227,8 @@ Returns the characters in the given range. Line endings are normalized to '\n'.

| Param | Type | Description |
| --- | --- | --- |
| start | <code>Object</code> | Start of range, inclusive |
| end | <code>Object</code> | End of range, exclusive |
| start | [<code>TextPosition</code>](#TextPosition) | Start of range, inclusive |
| end | [<code>TextPosition</code>](#TextPosition) | End of range, exclusive |

<a name="Document+getLine"></a>

Expand All @@ -243,9 +243,9 @@ Returns the text of the given line (excluding any line ending characters)

<a name="Document+posFromIndex"></a>

### document.posFromIndex(index) ⇒ <code>Object</code>
### document.posFromIndex(index) ⇒ [<code>TextPosition</code>](#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 [<code>Document</code>](#Document)
Expand Down Expand Up @@ -275,26 +275,26 @@ document not dirty and notifies listeners of the save.
**Kind**: instance method of [<code>Document</code>](#Document)
<a name="Document+adjustPosForChange"></a>

### document.adjustPosForChange(pos, textLines, start, end) ⇒ <code>Object</code>
### document.adjustPosForChange(pos, textLines, start, end) ⇒ [<code>TextPosition</code>](#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,
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 [<code>Document</code>](#Document)
**Returns**: <code>Object</code> - The adjusted position.
**Returns**: [<code>TextPosition</code>](#TextPosition) - The adjusted position.

| Param | Type | Description |
| --- | --- | --- |
| pos | <code>Object</code> | The position to adjust. |
| pos | [<code>TextPosition</code>](#TextPosition) | The position to adjust. |
| textLines | <code>Array.&lt;string&gt;</code> | The text of the change, split into an array of lines. |
| start | <code>Object</code> | The start of the edit. |
| end | <code>Object</code> | The end of the edit. |
| start | [<code>TextPosition</code>](#TextPosition) | The start of the edit. |
| end | [<code>TextPosition</code>](#TextPosition) | The end of the edit. |

<a name="Document+doMultipleEdits"></a>

### document.doMultipleEdits(edits, origin) ⇒ <code>Object</code>
### document.doMultipleEdits(edits, origin) ⇒ [<code>Array.&lt;SelectionRange&gt;</code>](#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
Expand All @@ -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 [<code>Document</code>](#Document)
**Returns**: <code>Object</code> - The list of passed selections adjusted for the performed edits, if any.
**Returns**: [<code>Array.&lt;SelectionRange&gt;</code>](#SelectionRange) - The list of passed selections adjusted for the performed edits, if any.

| Param | Type | Description |
| --- | --- | --- |
| edits | <code>Object</code> | 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 | <code>Array.&lt;Object&gt;</code> | 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 | <code>string</code> | An optional edit origin that's passed through to each replaceRange(). |

<a name="Document+getLanguage"></a>
Expand Down Expand Up @@ -347,3 +347,27 @@ Reloads the document from FileSystem
Normalizes line endings the same way CodeMirror would

**Kind**: static method of [<code>Document</code>](#Document)
<a name="TextPosition"></a>

## TextPosition : <code>Object</code>
**Kind**: global typedef
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| line | <code>number</code> | Zero-based line number |
| ch | <code>number</code> | Zero-based character offset |

<a name="SelectionRange"></a>

## SelectionRange : <code>Object</code>
**Kind**: global typedef
**Properties**

| Name | Type | Description |
| --- | --- | --- |
| start | [<code>TextPosition</code>](#TextPosition) | Start of the selection |
| end | [<code>TextPosition</code>](#TextPosition) | End of the selection |
| primary | <code>boolean</code> | Whether this is the primary selection |
| reversed | <code>boolean</code> | Whether the selection is reversed |

43 changes: 27 additions & 16 deletions src/document/Document.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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: <line number>, ch: <character offset>},
Expand Down Expand Up @@ -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.
Expand All @@ -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) {
Expand All @@ -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) {
Expand Down Expand Up @@ -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.<string>} 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
Expand Down Expand Up @@ -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.<Object>} edits
* Specifies the list of edits to perform in a manner similar to CodeMirror's `replaceRange`. This array
* will be mutated.
*
Expand Down Expand Up @@ -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.<SelectionRange>}
* The list of passed selections adjusted for the performed edits, if any.
*/

Expand Down
Loading