Skip to content

Commit c78dac6

Browse files
aboseabose
committed
fix: more docs build break
1 parent ed9b520 commit c78dac6

2 files changed

Lines changed: 69 additions & 34 deletions

File tree

‎docs/API-Reference/document/Document.md‎

Lines changed: 42 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,11 @@ const Document = brackets.getModule("document/Document")
2727
* [.replaceRange(text, start, end, origin)](#Document+replaceRange)
2828
* [.getRange(start, end)](#Document+getRange) ⇒ <code>string</code>
2929
* [.getLine(Zero-based)](#Document+getLine) ⇒ <code>string</code>
30-
* [.posFromIndex(index)](#Document+posFromIndex) ⇒ <code>Object</code>
30+
* [.posFromIndex(index)](#Document+posFromIndex) ⇒ [<code>TextPosition</code>](#TextPosition)
3131
* [.batchOperation(doOperation)](#Document+batchOperation)
3232
* [.notifySaved()](#Document+notifySaved)
33-
* [.adjustPosForChange(pos, textLines, start, end)](#Document+adjustPosForChange) ⇒ <code>Object</code>
34-
* [.doMultipleEdits(edits, origin)](#Document+doMultipleEdits) ⇒ <code>Object</code>
33+
* [.adjustPosForChange(pos, textLines, start, end)](#Document+adjustPosForChange) ⇒ [<code>TextPosition</code>](#TextPosition)
34+
* [.doMultipleEdits(edits, origin)](#Document+doMultipleEdits) ⇒ [<code>Array.&lt;SelectionRange&gt;</code>](#SelectionRange)
3535
* [.getLanguage()](#Document+getLanguage) ⇒ <code>Language</code>
3636
* [.isUntitled()](#Document+isUntitled) ⇒ <code>boolean</code>
3737
* [.reload()](#Document+reload) ⇒ <code>promise</code>
@@ -48,7 +48,7 @@ Document dispatches these events:
4848

4949
__change__ -- When the text of the editor changes (including due to undo/redo).
5050

51-
Passes ({'Document'}, {'ChangeList'}), where ChangeList is an array
51+
Passes (`Document`, `ChangeList`), where ChangeList is an array
5252
of change record objects. Each change record looks like:
5353
```js
5454
{ from: start of change, expressed as {line: <line number>, ch: <character offset>},
@@ -214,8 +214,8 @@ fixed when we migrate to use CodeMirror's native document-linking functionality.
214214
| Param | Type | Description |
215215
| --- | --- | --- |
216216
| text | <code>string</code> | Text to insert or replace the range with |
217-
| start | <code>Object</code> | Start of range, inclusive (if 'to' specified) or insertion point (if not) |
218-
| end | <code>Object</code> | End of range, exclusive; optional |
217+
| start | [<code>TextPosition</code>](#TextPosition) | Start of range, inclusive (if 'to' specified) or insertion point (if not) |
218+
| end | [<code>TextPosition</code>](#TextPosition) | End of range, exclusive; optional |
219219
| 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.) |
220220

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

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

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

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

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

246-
### document.posFromIndex(index) ⇒ <code>Object</code>
246+
### document.posFromIndex(index) ⇒ [<code>TextPosition</code>](#TextPosition)
247247
Given a character index within the document text (assuming \n newlines),
248-
returns the corresponding {line, ch} position. Works whether or not
248+
returns the corresponding `{line, ch}` position. Works whether or not
249249
a master editor is attached.
250250

251251
**Kind**: instance method of [<code>Document</code>](#Document)
@@ -275,26 +275,26 @@ document not dirty and notifies listeners of the save.
275275
**Kind**: instance method of [<code>Document</code>](#Document)
276276
<a name="Document+adjustPosForChange"></a>
277277

278-
### document.adjustPosForChange(pos, textLines, start, end) ⇒ <code>Object</code>
278+
### document.adjustPosForChange(pos, textLines, start, end) ⇒ [<code>TextPosition</code>](#TextPosition)
279279
Adjusts a given position taking a given replaceRange-type edit into account.
280280
If the position is within the original edit range (start and end inclusive),
281281
it gets pushed to the end of the content that replaced the range. Otherwise,
282282
if it's after the edit, it gets adjusted so it refers to the same character
283283
it did before the edit.
284284

285285
**Kind**: instance method of [<code>Document</code>](#Document)
286-
**Returns**: <code>Object</code> - The adjusted position.
286+
**Returns**: [<code>TextPosition</code>](#TextPosition) - The adjusted position.
287287

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

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

297-
### document.doMultipleEdits(edits, origin) ⇒ <code>Object</code>
297+
### document.doMultipleEdits(edits, origin) ⇒ [<code>Array.&lt;SelectionRange&gt;</code>](#SelectionRange)
298298
Helper function for edit operations that operate on multiple selections. Takes an "edit list"
299299
that specifies a list of replaceRanges that should occur, but where all the positions are with
300300
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,
312312
flat list of all the selections, suitable for passing to `setSelections()`.
313313

314314
**Kind**: instance method of [<code>Document</code>](#Document)
315-
**Returns**: <code>Object</code> - The list of passed selections adjusted for the performed edits, if any.
315+
**Returns**: [<code>Array.&lt;SelectionRange&gt;</code>](#SelectionRange) - The list of passed selections adjusted for the performed edits, if any.
316316

317317
| Param | Type | Description |
318318
| --- | --- | --- |
319-
| 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). |
319+
| 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). |
320320
| origin | <code>string</code> | An optional edit origin that's passed through to each replaceRange(). |
321321

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

349349
**Kind**: static method of [<code>Document</code>](#Document)
350+
<a name="TextPosition"></a>
351+
352+
## TextPosition : <code>Object</code>
353+
**Kind**: global typedef
354+
**Properties**
355+
356+
| Name | Type | Description |
357+
| --- | --- | --- |
358+
| line | <code>number</code> | Zero-based line number |
359+
| ch | <code>number</code> | Zero-based character offset |
360+
361+
<a name="SelectionRange"></a>
362+
363+
## SelectionRange : <code>Object</code>
364+
**Kind**: global typedef
365+
**Properties**
366+
367+
| Name | Type | Description |
368+
| --- | --- | --- |
369+
| start | [<code>TextPosition</code>](#TextPosition) | Start of the selection |
370+
| end | [<code>TextPosition</code>](#TextPosition) | End of the selection |
371+
| primary | <code>boolean</code> | Whether this is the primary selection |
372+
| reversed | <code>boolean</code> | Whether the selection is reversed |
373+

‎src/document/Document.js‎

Lines changed: 27 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,20 @@ define(function (require, exports, module) {
3333
CodeMirror = require("thirdparty/CodeMirror/lib/codemirror"),
3434
_ = require("thirdparty/lodash");
3535

36+
/**
37+
* @typedef {Object} TextPosition
38+
* @property {number} line - Zero-based line number
39+
* @property {number} ch - Zero-based character offset
40+
*/
41+
42+
/**
43+
* @typedef {Object} SelectionRange
44+
* @property {TextPosition} start - Start of the selection
45+
* @property {TextPosition} end - End of the selection
46+
* @property {boolean} primary - Whether this is the primary selection
47+
* @property {boolean} reversed - Whether the selection is reversed
48+
*/
49+
3650
/**
3751
* Model for the contents of a single file and its current modification state.
3852
* See DocumentManager documentation for important usage notes.
@@ -41,7 +55,7 @@ define(function (require, exports, module) {
4155
*
4256
* __change__ -- When the text of the editor changes (including due to undo/redo).
4357
*
44-
* Passes ({'Document'}, {'ChangeList'}), where ChangeList is an array
58+
* Passes (`Document`, `ChangeList`), where ChangeList is an array
4559
* of change record objects. Each change record looks like:
4660
*```js
4761
* { from: start of change, expressed as {line: <line number>, ch: <character offset>},
@@ -454,8 +468,8 @@ define(function (require, exports, module) {
454468
* fixed when we migrate to use CodeMirror's native document-linking functionality.
455469
*
456470
* @param {!string} text Text to insert or replace the range with
457-
* @param {!{line:number, ch:number}} start Start of range, inclusive (if 'to' specified) or insertion point (if not)
458-
* @param {?{line:number, ch:number}} end End of range, exclusive; optional
471+
* @param {!TextPosition} start Start of range, inclusive (if 'to' specified) or insertion point (if not)
472+
* @param {?TextPosition} end End of range, exclusive; optional
459473
* @param {?string} origin Optional string used to batch consecutive edits for undo.
460474
* If origin starts with "+", then consecutive edits with the same origin will be batched for undo if
461475
* they are close enough together in time.
@@ -473,8 +487,8 @@ define(function (require, exports, module) {
473487

474488
/**
475489
* Returns the characters in the given range. Line endings are normalized to '\n'.
476-
* @param {!{line:number, ch:number}} start Start of range, inclusive
477-
* @param {!{line:number, ch:number}} end End of range, exclusive
490+
* @param {!TextPosition} start Start of range, inclusive
491+
* @param {!TextPosition} end End of range, exclusive
478492
* @return {!string}
479493
*/
480494
Document.prototype.getRange = function (start, end) {
@@ -494,10 +508,10 @@ define(function (require, exports, module) {
494508

495509
/**
496510
* Given a character index within the document text (assuming \n newlines),
497-
* returns the corresponding {line, ch} position. Works whether or not
511+
* returns the corresponding `{line, ch}` position. Works whether or not
498512
* a master editor is attached.
499513
* @param {number} index - Zero-based character offset
500-
* @return {{line: number, ch: number}}
514+
* @return {TextPosition}
501515
*/
502516
Document.prototype.posFromIndex = function (index) {
503517
if (this._masterEditor) {
@@ -607,11 +621,11 @@ define(function (require, exports, module) {
607621
* it gets pushed to the end of the content that replaced the range. Otherwise,
608622
* if it's after the edit, it gets adjusted so it refers to the same character
609623
* it did before the edit.
610-
* @param {!{line:number, ch: number}} pos The position to adjust.
624+
* @param {!TextPosition} pos The position to adjust.
611625
* @param {!Array.<string>} textLines The text of the change, split into an array of lines.
612-
* @param {!{line: number, ch: number}} start The start of the edit.
613-
* @param {!{line: number, ch: number}} end The end of the edit.
614-
* @return {{line: number, ch: number}} The adjusted position.
626+
* @param {!TextPosition} start The start of the edit.
627+
* @param {!TextPosition} end The end of the edit.
628+
* @return {TextPosition} The adjusted position.
615629
*/
616630
Document.prototype.adjustPosForChange = function (pos, textLines, start, end) {
617631
// Same as CodeMirror.adjustForChange(), but that's a private function
@@ -662,10 +676,7 @@ define(function (require, exports, module) {
662676
* then this function will adjust them as necessary for the effects of other edits, and then return a
663677
* flat list of all the selections, suitable for passing to `setSelections()`.
664678
*
665-
* @param {!{edit: {text: string, start:{line: number, ch: number}, end: {line: number, ch: number} | undefined}
666-
* | {text: string, start:{line: number, ch: number}, end: {line: number, ch: number} | undefined},
667-
* selection: {start:{line:number, ch:number}, end:{line:number, ch:number},
668-
* primary:boolean, reversed: boolean, isBeforeEdit: boolean} | undefined}} edits
679+
* @param {!Array.<Object>} edits
669680
* Specifies the list of edits to perform in a manner similar to CodeMirror's `replaceRange`. This array
670681
* will be mutated.
671682
*
@@ -694,7 +705,7 @@ define(function (require, exports, module) {
694705
* the total bounds of edit groups must not overlap (e.g. edits in one group can't surround an edit from another group).
695706
*
696707
* @param {?string} origin An optional edit origin that's passed through to each replaceRange().
697-
* @return {{start:{line:number, ch:number}, end:{line:number, ch:number}, primary:boolean, reversed: boolean[]}}
708+
* @return {Array.<SelectionRange>}
698709
* The list of passed selections adjusted for the performed edits, if any.
699710
*/
700711

0 commit comments

Comments
 (0)