jsdoc vscode.d.ts
This commit is contained in:
parent
cc9e65cea2
commit
d62a44820f
152
src/vs/vscode.d.ts
vendored
152
src/vs/vscode.d.ts
vendored
|
@ -5,7 +5,6 @@
|
||||||
|
|
||||||
/*
|
/*
|
||||||
- comments are marked like this '<<< comment >>>'
|
- comments are marked like this '<<< comment >>>'
|
||||||
- I've fixed typos directly without comments
|
|
||||||
|
|
||||||
some global comments:
|
some global comments:
|
||||||
- I'm missing some structure/grouping in this file:
|
- I'm missing some structure/grouping in this file:
|
||||||
|
@ -24,23 +23,8 @@
|
||||||
"To get an instance of a {{FileSystemWatcher}} use {{workspace.createFileSystemWatcher}}."
|
"To get an instance of a {{FileSystemWatcher}} use {{workspace.createFileSystemWatcher}}."
|
||||||
- lots of class or method comments are still missing. If we cannot create all of them in time, we should focus on comments for non-obvious cases.
|
- lots of class or method comments are still missing. If we cannot create all of them in time, we should focus on comments for non-obvious cases.
|
||||||
I have added a "non-obvious" comment.
|
I have added a "non-obvious" comment.
|
||||||
- unclear when we have functions in a namespace and when we have resolve function and a sub namespace / interface. Examples are:
|
|
||||||
o workspace.openTextDocument() => return ITextDocument which opens a separate namespace
|
|
||||||
o vscode.language.register* functions. Could have been workspace.getLanguage(selector) => ILangauge
|
|
||||||
In general I think that having separate namespaces will help with scalibility. Results in smaller proposals in code complete.
|
|
||||||
window.activeTextEditor.###, window.statusBar.###, window.quickPick.###
|
|
||||||
|
|
||||||
- async programming style, Promise return and method naming
|
|
||||||
o we should make a statement how the async programming style works. What happens if I call a method and the actual operation can not be executed
|
|
||||||
in the main thread since the editor / model changed.
|
|
||||||
o would be good to have a naming theme that makes our model clear. We could for example use:
|
|
||||||
setXXX/applyXXX => Thenable. The operation is either done or rejected. An example is applying edits which get rejected if the model version doesn't exist anymore.
|
|
||||||
updateXXX => void. The operation is done but the result might never be observable. It could even be that the operation got dropped. Or we want to ensure the operation
|
|
||||||
is not observable. Example updateSelection. Otherwise people might think updateSelection(xxx).then(() => selction is at position xxx which might not be the case).
|
|
||||||
- label, names, descriptions: would be great to indicate if they show up in the user interface and therefore must be human readable.
|
- label, names, descriptions: would be great to indicate if they show up in the user interface and therefore must be human readable.
|
||||||
- usage of option bags. Most functions flatten all parameters other only take an option bag. We should be consistent here. If option bags they must be optional
|
|
||||||
- param: T | Thenable<T>: (e.g. showQuickPick). IMO we shouldn't pass Thenable as a param. It should be resolved outside> Otherwise we need to handle the error case
|
|
||||||
inside and even need to communicate that back to the outside.
|
|
||||||
*/
|
*/
|
||||||
|
|
||||||
|
|
||||||
|
@ -77,49 +61,44 @@ declare namespace vscode {
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Represents a line of text such as a line of source code
|
* Represents a line of text such as a line of source code.
|
||||||
* <<< Is a textLine live. E.g. when updating the document will a text line update as well. If not
|
*
|
||||||
* I would suggest to remove TextLine and add the methods to text document. Otherwise the object might
|
* TextLine objects are __immutable__. That means that when a [document](#TextDocument) changes
|
||||||
* be misleading.
|
* previsouly retrieved lines will not represent the latest state.
|
||||||
* >>>
|
|
||||||
*/
|
*/
|
||||||
export interface TextLine {
|
export interface TextLine {
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The zero-offset line number <<<better: 'zero-based' see https://en.wikipedia.org/wiki/Zero-based_numbering >>>
|
* The zero-base line number.
|
||||||
*
|
*
|
||||||
* @readonly
|
* @readonly
|
||||||
*/
|
*/
|
||||||
lineNumber: number;
|
lineNumber: number;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The text of this line without the
|
* The text of this line without the line separator characters.
|
||||||
* newline character <<< what's about CR/LF on Windows? better: 'line separator characters' >>>
|
|
||||||
*
|
*
|
||||||
* @readonly
|
* @readonly
|
||||||
*/
|
*/
|
||||||
text: string;
|
text: string;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The range this line covers without the
|
* The range this line covers without the line separator characters.
|
||||||
* newline character <<< what's about CR/LF on Windows? better: 'line separator characters' >>>
|
|
||||||
*
|
*
|
||||||
* @readonly
|
* @readonly
|
||||||
*/
|
*/
|
||||||
range: Range;
|
range: Range;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The range this line covers with the
|
* The range this line covers with the line separator characters.
|
||||||
* newline character <<< dito >>>
|
|
||||||
*
|
*
|
||||||
* @readonly
|
* @readonly
|
||||||
*/
|
*/
|
||||||
rangeIncludingLineBreak: Range;
|
rangeIncludingLineBreak: Range;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The offset of the first character which
|
* The offset of the first character which is not a whitespace character as defined
|
||||||
* isn't a whitespace character as defined
|
* by `/\s/`.
|
||||||
* by a `\s`-RegExp
|
|
||||||
*
|
*
|
||||||
* @readonly
|
* @readonly
|
||||||
*/
|
*/
|
||||||
|
@ -141,16 +120,17 @@ declare namespace vscode {
|
||||||
export interface TextDocument {
|
export interface TextDocument {
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Get the associated URI for this document. Most documents have the file://-scheme, indicating that they represent files on disk.
|
* The associated URI for this document. Most documents have the __file__-scheme, indicating that they
|
||||||
* However, some documents may have other schemes indicating that they are not available on disk.
|
* represent files on disk. However, some documents may have other schemes indicating that they are not
|
||||||
|
* available on disk.
|
||||||
*
|
*
|
||||||
* @readonly
|
* @readonly
|
||||||
*/
|
*/
|
||||||
uri: Uri;
|
uri: Uri;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns the file system path of the file associated with this document. Shorthand
|
* The file system path of the associated resource. Shorthand
|
||||||
* notation for `#uri.fsPath` <<< what if uri is not a file? >>>
|
* notation for `#uri.fsPath`. Independent of the uri scheme.
|
||||||
*
|
*
|
||||||
* @readonly
|
* @readonly
|
||||||
*/
|
*/
|
||||||
|
@ -164,7 +144,7 @@ declare namespace vscode {
|
||||||
isUntitled: boolean;
|
isUntitled: boolean;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The language identifier associated with this document.
|
* The identifier of the language associated with this document.
|
||||||
*
|
*
|
||||||
* @readonly
|
* @readonly
|
||||||
*/
|
*/
|
||||||
|
@ -232,25 +212,36 @@ declare namespace vscode {
|
||||||
positionAt(offset: number): Position;
|
positionAt(offset: number): Position;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Get the text in this document. If a range is provided the text contained
|
* Get the text of this document. A substring can be retrieved by providing
|
||||||
* by the range is returned. <<< if the range is larger than the TextDocument only the intersection is ... >>>
|
* a range. The range will be [adjusted](#TextDocument.validateRange).
|
||||||
|
*
|
||||||
|
* @param range Include only the text included by the range.
|
||||||
*/
|
*/
|
||||||
getText(range?: Range): string;
|
getText(range?: Range): string;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Get the word under a certain position. May return null if position is at whitespace, on empty line, etc.
|
* Get a word-range at the given position. By default words are defined by
|
||||||
* <<< what is a 'word'? >>>
|
* common separators, like space, -, _, etc. In addition, per languge custom
|
||||||
|
* [word definitions](#LanguageConfiguration.wordPattern) can be defined.
|
||||||
|
*
|
||||||
|
* @param position A position.
|
||||||
|
* @return A range spanning a word, or `undefined`.
|
||||||
*/
|
*/
|
||||||
getWordRangeAtPosition(position: Position): Range;
|
getWordRangeAtPosition(position: Position): Range;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Ensure a range sticks to the text.
|
* Ensure a range is completely contained in this document.
|
||||||
* <<< 'sticks'? better: ensure a range is completely contained in the TextDocument. >>>
|
*
|
||||||
|
* @param range A range.
|
||||||
|
* @return The given range or a new, adjusted range.
|
||||||
*/
|
*/
|
||||||
validateRange(range: Range): Range;
|
validateRange(range: Range): Range;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Ensure a position sticks to the text. // <<< dito >>>
|
* Ensure a position is completely contained in this document.
|
||||||
|
*
|
||||||
|
* @param position A position.
|
||||||
|
* @return The given position or a new, adjusted position.
|
||||||
*/
|
*/
|
||||||
validatePosition(position: Position): Position;
|
validatePosition(position: Position): Position;
|
||||||
}
|
}
|
||||||
|
@ -362,16 +353,21 @@ declare namespace vscode {
|
||||||
* Create a new range from two position. If `start` is not
|
* Create a new range from two position. If `start` is not
|
||||||
* before or equal to `end` the values will be swapped.
|
* before or equal to `end` the values will be swapped.
|
||||||
*
|
*
|
||||||
* @param start
|
* @param start A position.
|
||||||
* @param end
|
* @param end A position.
|
||||||
*/
|
*/
|
||||||
constructor(start: Position, end: Position);
|
constructor(start: Position, end: Position);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Create a new range from two (line,character)-pairs. The parameters
|
* Create a new range from four number. The parameters
|
||||||
* might be swapped so that start is before or equal to end.
|
* might be swapped so that start is before or equal to end.
|
||||||
|
*
|
||||||
|
* @param startLine A positive number or zero.
|
||||||
|
* @param startCharacter A positive number or zero.
|
||||||
|
* @param endLine A positive number or zero.
|
||||||
|
* @param endCharacter A positive number or zero.
|
||||||
*/
|
*/
|
||||||
constructor(startLine: number, startColumn: number, endLine: number, endColumn: number); // <<< use 'character' instead of 'column' >>>
|
constructor(startLine: number, startCharacter: number, endLine: number, endCharacter: number);
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* `true` iff `start` and `end` are equal.
|
* `true` iff `start` and `end` are equal.
|
||||||
|
@ -437,8 +433,13 @@ declare namespace vscode {
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Create a selection from four points.
|
* Create a selection from four points.
|
||||||
|
*
|
||||||
|
* @param anchorLine A positive number or zero.
|
||||||
|
* @param anchorCharacter A positive number or zero.
|
||||||
|
* @param activeLine A positive number or zero.
|
||||||
|
* @param activeCharacter A positive number or zero.
|
||||||
*/
|
*/
|
||||||
constructor(anchorLine: number, anchorColumn: number, activeLine: number, activeColumn: number); // <<< 'column' -> 'character' >>>
|
constructor(anchorLine: number, anchorCharacter: number, activeLine: number, activeCharacter: number);
|
||||||
/**
|
/**
|
||||||
* A selection is reversed if the [anchor](#Selection.anchor)
|
* A selection is reversed if the [anchor](#Selection.anchor)
|
||||||
* is equal to [start](#Selection.start) and if [active](#Selection.active)
|
* is equal to [start](#Selection.start) and if [active](#Selection.active)
|
||||||
|
@ -475,7 +476,7 @@ declare namespace vscode {
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* A text editor decoration type is a handle to additional styles in
|
* A text editor decoration type is a handle to additional styles in
|
||||||
* the editor.
|
* the editor.
|
||||||
*
|
*
|
||||||
* To get an instance of a `TextEditorDecorationType` use
|
* To get an instance of a `TextEditorDecorationType` use
|
||||||
* [createTextEditorDecorationType](#window.createTextEditorDecorationType).
|
* [createTextEditorDecorationType](#window.createTextEditorDecorationType).
|
||||||
|
@ -619,15 +620,12 @@ declare namespace vscode {
|
||||||
document: TextDocument;
|
document: TextDocument;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The primary selection on this text editor. In case the text editor has multiple selections this is the first selection as
|
* The primary selection on this text editor. Shorthand for `TextEditor.selections[0]`.
|
||||||
* in `TextEditor.selections[0]`. <<< and in the single selection case this is not true? This should always be true! >>>
|
|
||||||
* @see [updateSelection](#updateSelection)
|
|
||||||
*/
|
*/
|
||||||
selection: Selection;
|
selection: Selection;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The selections in this text editor.
|
* The selections in this text editor. The primary selection is always at index 0.
|
||||||
* @see [updateSelection](#updateSelection)
|
|
||||||
*/
|
*/
|
||||||
selections: Selection[];
|
selections: Selection[];
|
||||||
|
|
||||||
|
@ -638,17 +636,24 @@ declare namespace vscode {
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Perform an edit on the document associated with this text editor.
|
* Perform an edit on the document associated with this text editor.
|
||||||
* The passed in {{editBuilder}} is available only for the duration of the callback.
|
*
|
||||||
* <<< waht does 'available' mean? better: 'valid' >>>
|
* The given callback-function is invoked with an [edit-builder](#TextEditorEdit) which must
|
||||||
|
* be used to make edits. Note that the the edit-builder is only valid while the
|
||||||
|
* callback executes.
|
||||||
|
*
|
||||||
|
* @param callback A function which can make edits using an [edit-builder](#TextEditorEdit).
|
||||||
|
* @return A promise that resolve when the edits could be applied.
|
||||||
*/
|
*/
|
||||||
edit(callback: (editBuilder: TextEditorEdit) => void): Thenable<boolean>;
|
edit(callback: (editBuilder: TextEditorEdit) => void): Thenable<boolean>;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Adds a set of decorations to the text editor.
|
* Adds a set of decorations to the text editor. If a set of decorations already exists with
|
||||||
* You must first create a `TextEditorDecorationType`. <<< to create another object is probably true for 95% of all APIs; nuke this sentence! >>>
|
* the given [decoration type](#TextEditorDecorationType), they will be replaced.
|
||||||
* If a set of decorations already exists with the given type, they will be overwritten.
|
*
|
||||||
|
* @param decorationType A decoration type.
|
||||||
|
* @param rangesOrOptions Either [ranges](#Range) or more detailed [options](#DecorationOptions).
|
||||||
*/
|
*/
|
||||||
setDecorations(decorationType: TextEditorDecorationType, ranges: Range[] | DecorationOptions[]): void;
|
setDecorations(decorationType: TextEditorDecorationType, rangesOrOptions: Range[] | DecorationOptions[]): void;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Scroll as necessary in order to reveal the given range.
|
* Scroll as necessary in order to reveal the given range.
|
||||||
|
@ -676,17 +681,6 @@ declare namespace vscode {
|
||||||
hide(): void;
|
hide(): void;
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
|
||||||
* Denotes a column in the VS Code window. Columns used to show editors
|
|
||||||
* side by side.
|
|
||||||
* <<< another reason not to use the term 'column' for 'character' within a line >>>
|
|
||||||
* <<< this definition seems to be misplaced: it is not TextEditor related >>>
|
|
||||||
*/
|
|
||||||
export enum ViewColumn {
|
|
||||||
One = 1,
|
|
||||||
Two = 2,
|
|
||||||
Three = 3
|
|
||||||
}
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* A complex edit that will be applied on a TextEditor.
|
* A complex edit that will be applied on a TextEditor.
|
||||||
|
@ -910,12 +904,12 @@ declare namespace vscode {
|
||||||
export interface QuickPickItem {
|
export interface QuickPickItem {
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The main label of this item <<< is there another 'non-main' label? >>>
|
* A label. Will be rendered prominent.
|
||||||
*/
|
*/
|
||||||
label: string;
|
label: string;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* A description <<< for what is this used? >>>
|
* A description. Will be rendered less prominent.
|
||||||
*/
|
*/
|
||||||
description: string;
|
description: string;
|
||||||
}
|
}
|
||||||
|
@ -936,7 +930,7 @@ declare namespace vscode {
|
||||||
}
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Represents an actional item that is shown with an information, warning, or <<< what is an 'actional' item? >>>
|
* Represents an action that is shown with an information, warning, or
|
||||||
* error message
|
* error message
|
||||||
*
|
*
|
||||||
* @see #window.showInformationMessage
|
* @see #window.showInformationMessage
|
||||||
|
@ -1524,6 +1518,16 @@ declare namespace vscode {
|
||||||
dispose(): void;
|
dispose(): void;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Denotes a column in the VS Code window. Columns used to show editors
|
||||||
|
* side by side.
|
||||||
|
*/
|
||||||
|
export enum ViewColumn {
|
||||||
|
One = 1,
|
||||||
|
Two = 2,
|
||||||
|
Three = 3
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* An output channel is a container for readonly textual information.
|
* An output channel is a container for readonly textual information.
|
||||||
*
|
*
|
||||||
|
|
Loading…
Reference in a new issue