diff --git a/CHANGELOG.md b/CHANGELOG.md index 7f265a3f8..1d1a63fd9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ This changelog records changes to stable releases since 1.50.2. "TBA" changes he - feat: allow limited adjustment of launch config options during restart ([ref](https://github.com/microsoft/vscode/issues/118196)) - fix: worker processes breaking sessions when attaching multiple times ([ref](https://github.com/microsoft/vscode/issues/124045)) - fix: wrong name of autogenerated edge debug config +- chore: adopt new terminal profile contribution point ([ref](https://github.com/microsoft/vscode/issues/120369)) ## v1.56 (April 2021) diff --git a/package.json b/package.json index f2e5ab97d..765e71cb4 100644 --- a/package.json +++ b/package.json @@ -175,7 +175,8 @@ "onDebugInitialConfigurations", "onDebugResolve:node", "onDebugResolve:extensionHost", - "onDebugResolve:chrome" + "onDebugResolve:chrome", + "onTerminalProfile:extension.js-debug.debugTerminal" ], "extensionKind": [ "workspace" @@ -203,9 +204,9 @@ } ], "terminal": { - "types": [ + "profiles": [ { - "command": "extension.js-debug.createDebuggerTerminal", + "id": "extension.js-debug.debugTerminal", "title": "%debug.terminal.label%", "icon": "$(debug)" } diff --git a/src/targets/node/terminalNodeLauncher.ts b/src/targets/node/terminalNodeLauncher.ts index de8bbd6f1..f2c78aa48 100644 --- a/src/targets/node/terminalNodeLauncher.ts +++ b/src/targets/node/terminalNodeLauncher.ts @@ -129,9 +129,11 @@ export class TerminalNodeLauncher extends NodeLauncherBase({ workspaceState: { + keys: [], get(key: string, defaultValue?: T) { return workspaceState.get(key) ?? defaultValue; }, diff --git a/src/typings/vscode.d.ts b/src/typings/vscode.d.ts index 428e4e373..06415df5e 100644 --- a/src/typings/vscode.d.ts +++ b/src/typings/vscode.d.ts @@ -24,7 +24,7 @@ declare module 'vscode' { /** * The identifier of the actual command handler. - * @see [commands.registerCommand](#commands.registerCommand). + * @see {@link commands.registerCommand} */ command: string; @@ -43,7 +43,7 @@ declare module 'vscode' { /** * Represents a line of text, such as a line of source code. * - * TextLine objects are __immutable__. When a [document](#TextDocument) changes, + * TextLine objects are __immutable__. When a {@link TextDocument document} changes, * previously retrieved lines will not represent the latest state. */ export interface TextLine { @@ -76,14 +76,14 @@ declare module 'vscode' { /** * Whether this line is whitespace only, shorthand - * for [TextLine.firstNonWhitespaceCharacterIndex](#TextLine.firstNonWhitespaceCharacterIndex) === [TextLine.text.length](#TextLine.text). + * for {@link TextLine.firstNonWhitespaceCharacterIndex} === {@link TextLine.text TextLine.text.length}. */ readonly isEmptyOrWhitespace: boolean; } /** * Represents a text document, such as a source file. Text documents have - * [lines](#TextLine) and knowledge about an underlying resource like a file. + * {@link TextLine lines} and knowledge about an underlying resource like a file. */ export interface TextDocument { @@ -93,21 +93,21 @@ declare module 'vscode' { * *Note* that most documents use the `file`-scheme, which means they are files on disk. However, **not** all documents are * saved on disk and therefore the `scheme` must be checked before trying to access the underlying file or siblings on disk. * - * @see [FileSystemProvider](#FileSystemProvider) - * @see [TextDocumentContentProvider](#TextDocumentContentProvider) + * @see {@link FileSystemProvider} + * @see {@link TextDocumentContentProvider} */ readonly uri: Uri; /** * The file system path of the associated resource. Shorthand - * notation for [TextDocument.uri.fsPath](#TextDocument.uri). Independent of the uri scheme. + * notation for {@link TextDocument.uri TextDocument.uri.fsPath}. Independent of the uri scheme. */ readonly fileName: string; /** * Is this document representing an untitled file which has never been saved yet. *Note* that - * this does not mean the document will be saved to disk, use [`uri.scheme`](#Uri.scheme) - * to figure out where a document will be [saved](#FileSystemProvider), e.g. `file`, `ftp` etc. + * this does not mean the document will be saved to disk, use {@link Uri.scheme `uri.scheme`} + * to figure out where a document will be {@link FileSystemProvider saved}, e.g. `file`, `ftp` etc. */ readonly isUntitled: boolean; @@ -143,7 +143,7 @@ declare module 'vscode' { save(): Thenable; /** - * The [end of line](#EndOfLine) sequence that is predominately + * The {@link EndOfLine end of line} sequence that is predominately * used in this document. */ readonly eol: EndOfLine; @@ -159,7 +159,7 @@ declare module 'vscode' { * document are not reflected. * * @param line A line number in [0, lineCount). - * @return A [line](#TextLine). + * @return A {@link TextLine line}. */ lineAt(line: number): TextLine; @@ -168,18 +168,19 @@ declare module 'vscode' { * that the returned object is *not* live and changes to the * document are not reflected. * - * The position will be [adjusted](#TextDocument.validatePosition). + * The position will be {@link TextDocument.validatePosition adjusted}. + * + * @see {@link TextDocument.lineAt} * - * @see [TextDocument.lineAt](#TextDocument.lineAt) * @param position A position. - * @return A [line](#TextLine). + * @return A {@link TextLine line}. */ lineAt(position: Position): TextLine; /** * Converts the position to a zero-based offset. * - * The position will be [adjusted](#TextDocument.validatePosition). + * The position will be {@link TextDocument.validatePosition adjusted}. * * @param position A position. * @return A valid zero-based offset. @@ -190,13 +191,13 @@ declare module 'vscode' { * Converts a zero-based offset to a position. * * @param offset A zero-based offset. - * @return A valid [position](#Position). + * @return A valid {@link Position}. */ positionAt(offset: number): Position; /** * Get the text of this document. A substring can be retrieved by providing - * a range. The range will be [adjusted](#TextDocument.validateRange). + * a range. The range will be {@link TextDocument.validateRange adjusted}. * * @param range Include only the text included by the range. * @return The text inside the provided range or the entire text. @@ -206,16 +207,16 @@ declare module 'vscode' { /** * Get a word-range at the given position. By default words are defined by * common separators, like space, -, _, etc. In addition, per language custom - * [word definitions](#LanguageConfiguration.wordPattern) can be defined. It + * [word definitions} can be defined. It * is also possible to provide a custom regular expression. * * * *Note 1:* A custom regular expression must not match the empty string and * if it does, it will be ignored. * * *Note 2:* A custom regular expression will fail to match multiline strings * and in the name of speed regular expressions should not match words with - * spaces. Use [`TextLine.text`](#TextLine.text) for more complex, non-wordy, scenarios. + * spaces. Use {@link TextLine.text `TextLine.text`} for more complex, non-wordy, scenarios. * - * The position will be [adjusted](#TextDocument.validatePosition). + * The position will be {@link TextDocument.validatePosition adjusted}. * * @param position A position. * @param regex Optional regular expression that describes what a word is. @@ -244,8 +245,8 @@ declare module 'vscode' { * Represents a line and character position, such as * the position of the cursor. * - * Position objects are __immutable__. Use the [with](#Position.with) or - * [translate](#Position.translate) methods to derive new positions + * Position objects are __immutable__. Use the {@link Position.with with} or + * {@link Position.translate translate} methods to derive new positions * from an existing position. */ export class Position { @@ -343,8 +344,8 @@ declare module 'vscode' { /** * Create a new position derived from this position. * - * @param line Value that should be used as line value, default is the [existing value](#Position.line) - * @param character Value that should be used as character value, default is the [existing value](#Position.character) + * @param line Value that should be used as line value, default is the {@link Position.line existing value} + * @param character Value that should be used as character value, default is the {@link Position.character existing value} * @return A position where line and character are replaced by the given values. */ with(line?: number, character?: number): Position; @@ -361,21 +362,21 @@ declare module 'vscode' { /** * A range represents an ordered pair of two positions. - * It is guaranteed that [start](#Range.start).isBeforeOrEqual([end](#Range.end)) + * It is guaranteed that {@link Range.start start}.isBeforeOrEqual({@link Range.end end}) * - * Range objects are __immutable__. Use the [with](#Range.with), - * [intersection](#Range.intersection), or [union](#Range.union) methods + * Range objects are __immutable__. Use the {@link Range.with with}, + * {@link Range.intersection intersection}, or {@link Range.union union} methods * to derive new ranges from an existing range. */ export class Range { /** - * The start position. It is before or equal to [end](#Range.end). + * The start position. It is before or equal to {@link Range.end end}. */ readonly start: Position; /** - * The end position. It is after or equal to [start](#Range.start). + * The end position. It is after or equal to {@link Range.start start}. */ readonly end: Position; @@ -422,7 +423,7 @@ declare module 'vscode' { * Check if `other` equals this range. * * @param other A range. - * @return `true` when start and end are [equal](#Position.isEqual) to + * @return `true` when start and end are {@link Position.isEqual equal} to * start and end of this range. */ isEqual(other: Range): boolean; @@ -448,8 +449,8 @@ declare module 'vscode' { /** * Derived a new range from this range. * - * @param start A position that should be used as start. The default value is the [current start](#Range.start). - * @param end A position that should be used as end. The default value is the [current end](#Range.end). + * @param start A position that should be used as start. The default value is the {@link Range.start current start}. + * @param end A position that should be used as end. The default value is the {@link Range.end current end}. * @return A range derived from this range with the given start and end position. * If start and end are not different `this` range will be returned. */ @@ -472,13 +473,13 @@ declare module 'vscode' { /** * The position at which the selection starts. - * This position might be before or after [active](#Selection.active). + * This position might be before or after {@link Selection.active active}. */ anchor: Position; /** * The position of the cursor. - * This position might be before or after [anchor](#Selection.anchor). + * This position might be before or after {@link Selection.anchor anchor}. */ active: Position; @@ -501,13 +502,13 @@ declare module 'vscode' { constructor(anchorLine: number, anchorCharacter: number, activeLine: number, activeCharacter: number); /** - * A selection is reversed if [active](#Selection.active).isBefore([anchor](#Selection.anchor)). + * A selection is reversed if {@link Selection.active active}.isBefore({@link Selection.anchor anchor}). */ isReversed: boolean; } /** - * Represents sources that can cause [selection change events](#window.onDidChangeTextEditorSelection). + * Represents sources that can cause {@link window.onDidChangeTextEditorSelection selection change events}. */ export enum TextEditorSelectionChangeKind { /** @@ -525,62 +526,62 @@ declare module 'vscode' { } /** - * Represents an event describing the change in a [text editor's selections](#TextEditor.selections). + * Represents an event describing the change in a {@link TextEditor.selections text editor's selections}. */ export interface TextEditorSelectionChangeEvent { /** - * The [text editor](#TextEditor) for which the selections have changed. + * The {@link TextEditor text editor} for which the selections have changed. */ readonly textEditor: TextEditor; /** - * The new value for the [text editor's selections](#TextEditor.selections). + * The new value for the {@link TextEditor.selections text editor's selections}. */ - readonly selections: ReadonlyArray; + readonly selections: readonly Selection[]; /** - * The [change kind](#TextEditorSelectionChangeKind) which has triggered this + * The {@link TextEditorSelectionChangeKind change kind} which has triggered this * event. Can be `undefined`. */ readonly kind?: TextEditorSelectionChangeKind; } /** - * Represents an event describing the change in a [text editor's visible ranges](#TextEditor.visibleRanges). + * Represents an event describing the change in a {@link TextEditor.visibleRanges text editor's visible ranges}. */ export interface TextEditorVisibleRangesChangeEvent { /** - * The [text editor](#TextEditor) for which the visible ranges have changed. + * The {@link TextEditor text editor} for which the visible ranges have changed. */ readonly textEditor: TextEditor; /** - * The new value for the [text editor's visible ranges](#TextEditor.visibleRanges). + * The new value for the {@link TextEditor.visibleRanges text editor's visible ranges}. */ - readonly visibleRanges: ReadonlyArray; + readonly visibleRanges: readonly Range[]; } /** - * Represents an event describing the change in a [text editor's options](#TextEditor.options). + * Represents an event describing the change in a {@link TextEditor.options text editor's options}. */ export interface TextEditorOptionsChangeEvent { /** - * The [text editor](#TextEditor) for which the options have changed. + * The {@link TextEditor text editor} for which the options have changed. */ readonly textEditor: TextEditor; /** - * The new value for the [text editor's options](#TextEditor.options). + * The new value for the {@link TextEditor.options text editor's options}. */ readonly options: TextEditorOptions; } /** - * Represents an event describing the change of a [text editor's view column](#TextEditor.viewColumn). + * Represents an event describing the change of a {@link TextEditor.viewColumn text editor's view column}. */ export interface TextEditorViewColumnChangeEvent { /** - * The [text editor](#TextEditor) for which the view column has changed. + * The {@link TextEditor text editor} for which the view column has changed. */ readonly textEditor: TextEditor; /** - * The new value for the [text editor's view column](#TextEditor.viewColumn). + * The new value for the {@link TextEditor.viewColumn text editor's view column}. */ readonly viewColumn: ViewColumn; } @@ -634,14 +635,14 @@ declare module 'vscode' { } /** - * Represents a [text editor](#TextEditor)'s [options](#TextEditor.options). + * Represents a {@link TextEditor text editor}'s {@link TextEditor.options options}. */ export interface TextEditorOptions { /** * The size in spaces a tab takes. This is used for two purposes: * - the rendering width of a tab character; - * - the number of spaces to insert when [insertSpaces](#TextEditorOptions.insertSpaces) is true. + * - the number of spaces to insert when {@link TextEditorOptions.insertSpaces insertSpaces} is true. * * When getting a text editor's options, this property will always be a number (resolved). * When setting a text editor's options, this property is optional and it can be a number or `"auto"`. @@ -649,7 +650,7 @@ declare module 'vscode' { tabSize?: number | string; /** - * When pressing Tab insert [n](#TextEditorOptions.tabSize) spaces. + * When pressing Tab insert {@link TextEditorOptions.tabSize n} spaces. * When getting a text editor's options, this property will always be a boolean (resolved). * When setting a text editor's options, this property is optional and it can be a boolean or `"auto"`. */ @@ -672,10 +673,10 @@ declare module 'vscode' { /** * Represents a handle to a set of decorations - * sharing the same [styling options](#DecorationRenderOptions) in a [text editor](#TextEditor). + * sharing the same {@link DecorationRenderOptions styling options} in a {@link TextEditor text editor}. * * To get an instance of a `TextEditorDecorationType` use - * [createTextEditorDecorationType](#window.createTextEditorDecorationType). + * {@link window.createTextEditorDecorationType createTextEditorDecorationType}. */ export interface TextEditorDecorationType { @@ -691,7 +692,7 @@ declare module 'vscode' { } /** - * Represents different [reveal](#TextEditor.revealRange) strategies in a text editor. + * Represents different {@link TextEditor.revealRange reveal} strategies in a text editor. */ export enum TextEditorRevealType { /** @@ -714,7 +715,7 @@ declare module 'vscode' { } /** - * Represents different positions for rendering a decoration in an [overview ruler](#DecorationRenderOptions.overviewRulerLane). + * Represents different positions for rendering a decoration in an {@link DecorationRenderOptions.overviewRulerLane overview ruler}. * The overview ruler supports three lanes. */ export enum OverviewRulerLane { @@ -747,31 +748,31 @@ declare module 'vscode' { } /** - * Represents options to configure the behavior of showing a [document](#TextDocument) in an [editor](#TextEditor). + * Represents options to configure the behavior of showing a {@link TextDocument document} in an {@link TextEditor editor}. */ export interface TextDocumentShowOptions { /** - * An optional view column in which the [editor](#TextEditor) should be shown. - * The default is the [active](#ViewColumn.Active), other values are adjusted to - * be `Min(column, columnCount + 1)`, the [active](#ViewColumn.Active)-column is - * not adjusted. Use [`ViewColumn.Beside`](#ViewColumn.Beside) to open the + * An optional view column in which the {@link TextEditor editor} should be shown. + * The default is the {@link ViewColumn.Active active}, other values are adjusted to + * be `Min(column, columnCount + 1)`, the {@link ViewColumn.Active active}-column is + * not adjusted. Use {@link ViewColumn.Beside `ViewColumn.Beside`} to open the * editor to the side of the currently active one. */ viewColumn?: ViewColumn; /** - * An optional flag that when `true` will stop the [editor](#TextEditor) from taking focus. + * An optional flag that when `true` will stop the {@link TextEditor editor} from taking focus. */ preserveFocus?: boolean; /** - * An optional flag that controls if an [editor](#TextEditor)-tab will be replaced + * An optional flag that controls if an {@link TextEditor editor}-tab will be replaced * with the next editor or if it will be kept. */ preview?: boolean; /** - * An optional selection to apply for the document in the [editor](#TextEditor). + * An optional selection to apply for the document in the {@link TextEditor editor}. */ selection?: Range; } @@ -790,7 +791,7 @@ declare module 'vscode' { } /** - * A reference to a named icon. Currently, [File](#ThemeIcon.File), [Folder](#ThemeIcon.Folder), + * A reference to a named icon. Currently, {@link ThemeIcon.File File}, {@link ThemeIcon.Folder Folder}, * and [ThemeIcon ids](https://code.visualstudio.com/api/references/icons-in-labels#icon-listing) are supported. * Using a theme icon is preferred over a custom icon as it gives product theme authors the possibility to change the icons. * @@ -814,25 +815,25 @@ declare module 'vscode' { readonly id: string; /** - * The optional ThemeColor of the icon. The color is currently only used in [TreeItem](#TreeItem). + * The optional ThemeColor of the icon. The color is currently only used in {@link TreeItem}. */ readonly color?: ThemeColor; /** * Creates a reference to a theme icon. * @param id id of the icon. The available icons are listed in https://code.visualstudio.com/api/references/icons-in-labels#icon-listing. - * @param color optional `ThemeColor` for the icon. The color is currently only used in [TreeItem](#TreeItem). + * @param color optional `ThemeColor` for the icon. The color is currently only used in {@link TreeItem}. */ constructor(id: string, color?: ThemeColor); } /** - * Represents theme specific rendering styles for a [text editor decoration](#TextEditorDecorationType). + * Represents theme specific rendering styles for a {@link TextEditorDecorationType text editor decoration}. */ export interface ThemableDecorationRenderOptions { /** * Background color of the decoration. Use rgba() and define transparent background colors to play well with other decorations. - * Alternatively a color from the color registry can be [referenced](#ThemeColor). + * Alternatively a color from the color registry can be {@link ThemeColor referenced}. */ backgroundColor?: string | ThemeColor; @@ -1010,7 +1011,7 @@ declare module 'vscode' { } /** - * Represents rendering styles for a [text editor decoration](#TextEditorDecorationType). + * Represents rendering styles for a {@link TextEditorDecorationType text editor decoration}. */ export interface DecorationRenderOptions extends ThemableDecorationRenderOptions { /** @@ -1042,7 +1043,7 @@ declare module 'vscode' { } /** - * Represents options for a specific decoration in a [decoration set](#TextEditorDecorationType). + * Represents options for a specific decoration in a {@link TextEditorDecorationType decoration set}. */ export interface DecorationOptions { @@ -1088,7 +1089,7 @@ declare module 'vscode' { } /** - * Represents an editor that is attached to a [document](#TextDocument). + * Represents an editor that is attached to a {@link TextDocument document}. */ export interface TextEditor { @@ -1128,18 +1129,18 @@ declare module 'vscode' { /** * Perform an edit on the document associated with this text editor. * - * The given callback-function is invoked with an [edit-builder](#TextEditorEdit) which must + * The given callback-function is invoked with an {@link TextEditorEdit edit-builder} which must * be used to make edits. Note that the edit-builder is only valid while the * callback executes. * - * @param callback A function which can create edits using an [edit-builder](#TextEditorEdit). + * @param callback A function which can create edits using an {@link TextEditorEdit edit-builder}. * @param options The undo/redo behavior around this edit. By default, undo stops will be created before and after this edit. * @return A promise that resolves with a value indicating if the edits could be applied. */ edit(callback: (editBuilder: TextEditorEdit) => void, options?: { undoStopBefore: boolean; undoStopAfter: boolean; }): Thenable; /** - * Insert a [snippet](#SnippetString) and put the editor into snippet mode. "Snippet mode" + * Insert a {@link SnippetString snippet} and put the editor into snippet mode. "Snippet mode" * means the editor adds placeholders and additional cursors so that the user can complete * or accept the snippet. * @@ -1149,18 +1150,20 @@ declare module 'vscode' { * @return A promise that resolves with a value indicating if the snippet could be inserted. Note that the promise does not signal * that the snippet is completely filled-in or accepted. */ - insertSnippet(snippet: SnippetString, location?: Position | Range | ReadonlyArray | ReadonlyArray, options?: { undoStopBefore: boolean; undoStopAfter: boolean; }): Thenable; + insertSnippet(snippet: SnippetString, location?: Position | Range | readonly Position[] | readonly Range[], options?: { undoStopBefore: boolean; undoStopAfter: boolean; }): Thenable; /** * Adds a set of decorations to the text editor. If a set of decorations already exists with - * the given [decoration type](#TextEditorDecorationType), they will be replaced. + * the given {@link TextEditorDecorationType decoration type}, they will be replaced. If + * `rangesOrOptions` is empty, the existing decorations with the given {@link TextEditorDecorationType decoration type} + * will be removed. * - * @see [createTextEditorDecorationType](#window.createTextEditorDecorationType). + * @see {@link window.createTextEditorDecorationType createTextEditorDecorationType}. * * @param decorationType A decoration type. - * @param rangesOrOptions Either [ranges](#Range) or more detailed [options](#DecorationOptions). + * @param rangesOrOptions Either {@link Range ranges} or more detailed {@link DecorationOptions options}. */ - setDecorations(decorationType: TextEditorDecorationType, rangesOrOptions: Range[] | DecorationOptions[]): void; + setDecorations(decorationType: TextEditorDecorationType, rangesOrOptions: readonly Range[] | readonly DecorationOptions[]): void; /** * Scroll as indicated by `revealType` in order to reveal the given range. @@ -1173,9 +1176,9 @@ declare module 'vscode' { /** * Show the text editor. * - * @deprecated Use [window.showTextDocument](#window.showTextDocument) instead. + * @deprecated Use {@link window.showTextDocument} instead. * - * @param column The [column](#ViewColumn) in which to show this editor. + * @param column The {@link ViewColumn column} in which to show this editor. * This method shows unexpected behavior and will be removed in the next major update. */ show(column?: ViewColumn): void; @@ -1190,7 +1193,7 @@ declare module 'vscode' { } /** - * Represents an end of line character sequence in a [document](#TextDocument). + * Represents an end of line character sequence in a {@link TextDocument document}. */ export enum EndOfLine { /** @@ -1206,12 +1209,12 @@ declare module 'vscode' { /** * A complex edit that will be applied in one transaction on a TextEditor. * This holds a description of the edits and if the edits are valid (i.e. no overlapping regions, document was not changed in the meantime, etc.) - * they can be applied on a [document](#TextDocument) associated with a [text editor](#TextEditor). + * they can be applied on a {@link TextDocument document} associated with a {@link TextEditor text editor}. */ export interface TextEditorEdit { /** * Replace a certain text region with a new value. - * You can use \r\n or \n in `value` and they will be normalized to the current [document](#TextDocument). + * You can use \r\n or \n in `value` and they will be normalized to the current {@link TextDocument document}. * * @param location The range this operation should remove. * @param value The new text this operation should insert after removing `location`. @@ -1220,8 +1223,8 @@ declare module 'vscode' { /** * Insert text at a location. - * You can use \r\n or \n in `value` and they will be normalized to the current [document](#TextDocument). - * Although the equivalent text edit can be made with [replace](#TextEditorEdit.replace), `insert` will produce a different resulting selection (it will get moved). + * You can use \r\n or \n in `value` and they will be normalized to the current {@link TextDocument document}. + * Although the equivalent text edit can be made with {@link TextEditorEdit.replace replace}, `insert` will produce a different resulting selection (it will get moved). * * @param location The position where the new text should be inserted. * @param value The new text this operation should insert. @@ -1238,7 +1241,7 @@ declare module 'vscode' { /** * Set the end of line sequence. * - * @param endOfLine The new end of line for the [document](#TextDocument). + * @param endOfLine The new end of line for the {@link TextDocument document}. */ setEndOfLine(endOfLine: EndOfLine): void; } @@ -1257,7 +1260,7 @@ declare module 'vscode' { * as all uris should have a scheme. To avoid breakage of existing code the optional * `strict`-argument has been added. We *strongly* advise to use it, e.g. `Uri.parse('my:uri', true)` * - * @see [Uri.toString](#Uri.toString) + * @see {@link Uri.toString} * @param value The string value of an Uri. * @param strict Throw an error when `value` is empty or when no `scheme` can be parsed. * @return A new Uri instance. @@ -1265,10 +1268,10 @@ declare module 'vscode' { static parse(value: string, strict?: boolean): Uri; /** - * Create an URI from a file system path. The [scheme](#Uri.scheme) + * Create an URI from a file system path. The {@link Uri.scheme scheme} * will be `file`. * - * The *difference* between `Uri#parse` and `Uri#file` is that the latter treats the argument + * The *difference* between {@link Uri.parse} and {@link Uri.file} is that the latter treats the argument * as path, not as stringified-uri. E.g. `Uri.file(path)` is *not* the same as * `Uri.parse('file://' + path)` because the path might contain characters that are * interpreted (# and ?). See the following sample: @@ -1311,6 +1314,15 @@ declare module 'vscode' { */ static joinPath(base: Uri, ...pathSegments: string[]): Uri; + /** + * Create an URI from its component parts + * + * @see {@link Uri.toString} + * @param components The component parts of an Uri. + * @return A new Uri instance. + */ + static from(components: { scheme: string; authority?: string; path?: string; query?: string; fragment?: string }): Uri; + /** * Use the `file` and `parse` factory functions to create new `Uri` objects. */ @@ -1354,7 +1366,7 @@ declare module 'vscode' { * * The resulting string shall *not* be used for display purposes but * for disk operations, like `readFile` et al. * - * The *difference* to the [`path`](#Uri.path)-property is the use of the platform specific + * The *difference* to the {@link Uri.path `path`}-property is the use of the platform specific * path separator and the handling of UNC paths. The sample below outlines the difference: * ```ts const u = URI.parse('file://server/c$/folder/file.txt') @@ -1385,7 +1397,7 @@ declare module 'vscode' { * Returns a string representation of this Uri. The representation and normalization * of a URI depends on the scheme. * - * * The resulting string can be safely used with [Uri.parse](#Uri.parse). + * * The resulting string can be safely used with {@link Uri.parse}. * * The resulting string shall *not* be used for display purposes. * * *Note* that the implementation will encode _aggressive_ which often leads to unexpected, @@ -1414,7 +1426,7 @@ declare module 'vscode' { * for completion items because the user continued to type. * * To get an instance of a `CancellationToken` use a - * [CancellationTokenSource](#CancellationTokenSource). + * {@link CancellationTokenSource}. */ export interface CancellationToken { @@ -1424,13 +1436,13 @@ declare module 'vscode' { isCancellationRequested: boolean; /** - * An [event](#Event) which fires upon cancellation. + * An {@link Event} which fires upon cancellation. */ onCancellationRequested: Event; } /** - * A cancellation source creates and controls a [cancellation token](#CancellationToken). + * A cancellation source creates and controls a {@link CancellationToken cancellation token}. */ export class CancellationTokenSource { @@ -1453,7 +1465,7 @@ declare module 'vscode' { /** * An error type that should be used to signal cancellation of an operation. * - * This type can be used in response to a [cancellation token](#CancellationToken) + * This type can be used in response to a {@link CancellationToken cancellation token} * being cancelled or when an operation is being cancelled by the * executor of that operation. */ @@ -1512,18 +1524,18 @@ declare module 'vscode' { * * @param listener The listener function will be called when the event happens. * @param thisArgs The `this`-argument which will be used when calling the event listener. - * @param disposables An array to which a [disposable](#Disposable) will be added. + * @param disposables An array to which a {@link Disposable} will be added. * @return A disposable which unsubscribes the event listener. */ (listener: (e: T) => any, thisArgs?: any, disposables?: Disposable[]): Disposable; } /** - * An event emitter can be used to create and manage an [event](#Event) for others + * An event emitter can be used to create and manage an {@link Event} for others * to subscribe to. One emitter always owns one event. * * Use this class if you want to provide event from within your extension, for instance - * inside a [TextDocumentContentProvider](#TextDocumentContentProvider) or when providing + * inside a {@link TextDocumentContentProvider} or when providing * API to other extensions. */ export class EventEmitter { @@ -1534,7 +1546,7 @@ declare module 'vscode' { event: Event; /** - * Notify all subscribers of the [event](#EventEmitter.event). Failure + * Notify all subscribers of the {@link EventEmitter.event event}. Failure * of one or more listener will not fail this function call. * * @param data The event object. @@ -1549,10 +1561,10 @@ declare module 'vscode' { /** * A file system watcher notifies about changes to files and folders - * on disk or from other [FileSystemProviders](#FileSystemProvider). + * on disk or from other {@link FileSystemProvider FileSystemProviders}. * * To get an instance of a `FileSystemWatcher` use - * [createFileSystemWatcher](#workspace.createFileSystemWatcher). + * {@link workspace.createFileSystemWatcher createFileSystemWatcher}. */ export interface FileSystemWatcher extends Disposable { @@ -1594,9 +1606,9 @@ declare module 'vscode' { * A text document content provider allows to add readonly documents * to the editor, such as source from a dll or generated html from md. * - * Content providers are [registered](#workspace.registerTextDocumentContentProvider) - * for a [uri-scheme](#Uri.scheme). When a uri with that scheme is to - * be [loaded](#workspace.openTextDocument) the content provider is + * Content providers are {@link workspace.registerTextDocumentContentProvider registered} + * for a {@link Uri.scheme uri-scheme}. When a uri with that scheme is to + * be {@link workspace.openTextDocument loaded} the content provider is * asked. */ export interface TextDocumentContentProvider { @@ -1610,13 +1622,13 @@ declare module 'vscode' { * Provide textual content for a given uri. * * The editor will use the returned string-content to create a readonly - * [document](#TextDocument). Resources allocated should be released when - * the corresponding document has been [closed](#workspace.onDidCloseTextDocument). + * {@link TextDocument document}. Resources allocated should be released when + * the corresponding document has been {@link workspace.onDidCloseTextDocument closed}. * - * **Note**: The contents of the created [document](#TextDocument) might not be + * **Note**: The contents of the created {@link TextDocument document} might not be * identical to the provided text due to end-of-line-sequence normalization. * - * @param uri An uri which scheme matches the scheme this provider was [registered](#workspace.registerTextDocumentContentProvider) for. + * @param uri An uri which scheme matches the scheme this provider was {@link workspace.registerTextDocumentContentProvider registered} for. * @param token A cancellation token. * @return A string or a thenable that resolves to such. */ @@ -1630,20 +1642,20 @@ declare module 'vscode' { export interface QuickPickItem { /** - * A human-readable string which is rendered prominent. Supports rendering of [theme icons](#ThemeIcon) via + * A human-readable string which is rendered prominent. Supports rendering of {@link ThemeIcon theme icons} via * the `$()`-syntax. */ label: string; /** * A human-readable string which is rendered less prominent in the same line. Supports rendering of - * [theme icons](#ThemeIcon) via the `$()`-syntax. + * {@link ThemeIcon theme icons} via the `$()`-syntax. */ description?: string; /** * A human-readable string which is rendered less prominent in a separate line. Supports rendering of - * [theme icons](#ThemeIcon) via the `$()`-syntax. + * {@link ThemeIcon theme icons} via the `$()`-syntax. */ detail?: string; @@ -1651,7 +1663,7 @@ declare module 'vscode' { * Optional flag indicating if this item is picked initially. * (Only honored when the picker allows multiple selections.) * - * @see [QuickPickOptions.canPickMany](#QuickPickOptions.canPickMany) + * @see {@link QuickPickOptions.canPickMany} */ picked?: boolean; @@ -1703,7 +1715,7 @@ declare module 'vscode' { } /** - * Options to configure the behaviour of the [workspace folder](#WorkspaceFolder) pick UI. + * Options to configure the behaviour of the {@link WorkspaceFolder workspace folder} pick UI. */ export interface WorkspaceFolderPickOptions { @@ -1812,9 +1824,9 @@ declare module 'vscode' { * Represents an action that is shown with an information, warning, or * error message. * - * @see [showInformationMessage](#window.showInformationMessage) - * @see [showWarningMessage](#window.showWarningMessage) - * @see [showErrorMessage](#window.showErrorMessage) + * @see {@link window.showInformationMessage showInformationMessage} + * @see {@link window.showWarningMessage showWarningMessage} + * @see {@link window.showErrorMessage showErrorMessage} */ export interface MessageItem { @@ -1836,9 +1848,9 @@ declare module 'vscode' { /** * Options to configure the behavior of the message. * - * @see [showInformationMessage](#window.showInformationMessage) - * @see [showWarningMessage](#window.showWarningMessage) - * @see [showErrorMessage](#window.showErrorMessage) + * @see {@link window.showInformationMessage showInformationMessage} + * @see {@link window.showWarningMessage showWarningMessage} + * @see {@link window.showErrorMessage showErrorMessage} */ export interface MessageOptions { @@ -1864,7 +1876,7 @@ declare module 'vscode' { value?: string; /** - * Selection of the prefilled [`value`](#InputBoxOptions.value). Defined as tuple of two number where the + * Selection of the prefilled {@link InputBoxOptions.value `value`}. Defined as tuple of two number where the * first is the inclusive start index and the second the exclusive end index. When `undefined` the whole * word will be selected, when empty (start equals end) only the cursor will be set, * otherwise the defined range will be selected. @@ -1905,7 +1917,7 @@ declare module 'vscode' { /** * A relative pattern is a helper to construct glob patterns that are matched * relatively to a base file path. The base path can either be an absolute file - * path as string or uri or a [workspace folder](#WorkspaceFolder), which is the + * path as string or uri or a {@link WorkspaceFolder workspace folder}, which is the * preferred way of creating the relative pattern. */ export class RelativePattern { @@ -1942,7 +1954,7 @@ declare module 'vscode' { * ``` * * @param base A base to which this pattern will be matched against relatively. It is recommended - * to pass in a [workspace folder](#WorkspaceFolder) if the pattern should match inside the workspace. + * to pass in a {@link WorkspaceFolder workspace folder} if the pattern should match inside the workspace. * Otherwise, a uri or string should only be used if the pattern is for a file path outside the workspace. * @param pattern A file glob pattern like `*.{ts,js}` that will be matched on paths relative to the base. */ @@ -1951,7 +1963,7 @@ declare module 'vscode' { /** * A file glob pattern to match file paths against. This can either be a glob pattern string - * (like `**​/*.{ts,js}` or `*.{ts,js}`) or a [relative pattern](#RelativePattern). + * (like `**​/*.{ts,js}` or `*.{ts,js}`) or a {@link RelativePattern relative pattern}. * * Glob patterns can have the following syntax: * * `*` to match one or more characters in a path segment @@ -1962,7 +1974,7 @@ declare module 'vscode' { * * `[!...]` to negate a range of characters to match in a path segment (e.g., `example.[!0-9]` to match on `example.a`, `example.b`, but not `example.0`) * * Note: a backslash (`\`) is not valid within a glob pattern. If you have an existing file - * path to match against, consider to use the [relative pattern](#RelativePattern) support + * path to match against, consider to use the {@link RelativePattern relative pattern} support * that takes care of converting any backslash into slash. Otherwise, make sure to convert * any backslash to slash when creating the glob pattern. */ @@ -1970,8 +1982,8 @@ declare module 'vscode' { /** * A document filter denotes a document by different properties like - * the [language](#TextDocument.languageId), the [scheme](#Uri.scheme) of - * its resource, or a glob-pattern that is applied to the [path](#TextDocument.fileName). + * the {@link TextDocument.languageId language}, the {@link Uri.scheme scheme} of + * its resource, or a glob-pattern that is applied to the {@link TextDocument.fileName path}. * * @example A language filter that applies to typescript files on disk * { language: 'typescript', scheme: 'file' } @@ -1987,20 +1999,20 @@ declare module 'vscode' { readonly language?: string; /** - * A Uri [scheme](#Uri.scheme), like `file` or `untitled`. + * A Uri {@link Uri.scheme scheme}, like `file` or `untitled`. */ readonly scheme?: string; /** - * A [glob pattern](#GlobPattern) that is matched on the absolute path of the document. Use a [relative pattern](#RelativePattern) - * to filter documents to a [workspace folder](#WorkspaceFolder). + * A {@link GlobPattern glob pattern} that is matched on the absolute path of the document. Use a {@link RelativePattern relative pattern} + * to filter documents to a {@link WorkspaceFolder workspace folder}. */ readonly pattern?: GlobPattern; } /** * A language selector is the combination of one or many language identifiers - * and [language filters](#DocumentFilter). + * and {@link DocumentFilter language filters}. * * *Note* that a document selector that is just a language identifier selects *all* * documents, even those that are not saved on disk. Only use such selectors when @@ -2013,12 +2025,12 @@ declare module 'vscode' { export type DocumentSelector = DocumentFilter | string | ReadonlyArray; /** - * A provider result represents the values a provider, like the [`HoverProvider`](#HoverProvider), + * A provider result represents the values a provider, like the {@link HoverProvider `HoverProvider`}, * may return. For once this is the actual result type `T`, like `Hover`, or a thenable that resolves * to that type `T`. In addition, `null` and `undefined` can be returned - either directly or from a * thenable. * - * The snippets below are all valid implementations of the [`HoverProvider`](#HoverProvider): + * The snippets below are all valid implementations of the {@link HoverProvider `HoverProvider`}: * * ```ts * let a: HoverProvider = { @@ -2049,7 +2061,7 @@ declare module 'vscode' { * * Kinds are a hierarchical list of identifiers separated by `.`, e.g. `"refactor.extract.function"`. * - * Code action kinds are used by VS Code for UI elements such as the refactoring context menu. Users + * Code action kinds are used by the editor for UI elements such as the refactoring context menu. Users * can also trigger code actions with a specific kind with the `editor.action.codeAction` command. */ export class CodeActionKind { @@ -2188,7 +2200,7 @@ declare module 'vscode' { /** * Contains additional diagnostic information about the context in which - * a [code action](#CodeActionProvider.provideCodeActions) is run. + * a {@link CodeActionProvider.provideCodeActions code action} is run. */ export interface CodeActionContext { /** @@ -2199,7 +2211,7 @@ declare module 'vscode' { /** * An array of diagnostics. */ - readonly diagnostics: ReadonlyArray; + readonly diagnostics: readonly Diagnostic[]; /** * Requested kind of actions to return. @@ -2213,7 +2225,7 @@ declare module 'vscode' { * A code action represents a change that can be performed in code, e.g. to fix a problem or * to refactor code. * - * A CodeAction must set either [`edit`](#CodeAction.edit) and/or a [`command`](#CodeAction.command). If both are supplied, the `edit` is applied first, then the command is executed. + * A CodeAction must set either {@link CodeAction.edit `edit`} and/or a {@link CodeAction.command `command`}. If both are supplied, the `edit` is applied first, then the command is executed. */ export class CodeAction { @@ -2223,25 +2235,25 @@ declare module 'vscode' { title: string; /** - * A [workspace edit](#WorkspaceEdit) this code action performs. + * A {@link WorkspaceEdit workspace edit} this code action performs. */ edit?: WorkspaceEdit; /** - * [Diagnostics](#Diagnostic) that this code action resolves. + * {@link Diagnostic Diagnostics} that this code action resolves. */ diagnostics?: Diagnostic[]; /** - * A [command](#Command) this code action executes. + * A {@link Command} this code action executes. * - * If this command throws an exception, VS Code displays the exception message to users in the editor at the + * If this command throws an exception, the editor displays the exception message to users in the editor at the * current cursor position. */ command?: Command; /** - * [Kind](#CodeActionKind) of the code action. + * {@link CodeActionKind Kind} of the code action. * * Used to filter code actions. */ @@ -2266,7 +2278,7 @@ declare module 'vscode' { * of code action, such as refactorings. * * - If the user has a [keybinding](https://code.visualstudio.com/docs/editor/refactoring#_keybindings-for-code-actions) - * that auto applies a code action and only a disabled code actions are returned, VS Code will show the user an + * that auto applies a code action and only a disabled code actions are returned, the editor will show the user an * error message with `reason` in the editor. */ disabled?: { @@ -2281,8 +2293,8 @@ declare module 'vscode' { /** * Creates a new code action. * - * A code action must have at least a [title](#CodeAction.title) and [edits](#CodeAction.edit) - * and/or a [command](#CodeAction.command). + * A code action must have at least a {@link CodeAction.title title} and {@link CodeAction.edit edits} + * and/or a {@link CodeAction.command command}. * * @param title The title of the code action. * @param kind The kind of the code action. @@ -2294,7 +2306,7 @@ declare module 'vscode' { * The code action interface defines the contract between extensions and * the [lightbulb](https://code.visualstudio.com/docs/editor/editingevolved#_code-action) feature. * - * A code action can be any command that is [known](#commands.getCommands) to the system. + * A code action can be any command that is {@link commands.getCommands known} to the system. */ export interface CodeActionProvider { /** @@ -2315,7 +2327,7 @@ declare module 'vscode' { provideCodeActions(document: TextDocument, range: Range | Selection, context: CodeActionContext, token: CancellationToken): ProviderResult<(Command | T)[]>; /** - * Given a code action fill in its [`edit`](#CodeAction.edit)-property. Changes to + * Given a code action fill in its {@link CodeAction.edit `edit`}-property. Changes to * all other properties, like title, are ignored. A code action that has an edit * will not be resolved. * @@ -2332,28 +2344,28 @@ declare module 'vscode' { } /** - * Metadata about the type of code actions that a [CodeActionProvider](#CodeActionProvider) provides. + * Metadata about the type of code actions that a {@link CodeActionProvider} provides. */ export interface CodeActionProviderMetadata { /** - * List of [CodeActionKinds](#CodeActionKind) that a [CodeActionProvider](#CodeActionProvider) may return. + * List of {@link CodeActionKind CodeActionKinds} that a {@link CodeActionProvider} may return. * * This list is used to determine if a given `CodeActionProvider` should be invoked or not. * To avoid unnecessary computation, every `CodeActionProvider` should list use `providedCodeActionKinds`. The * list of kinds may either be generic, such as `[CodeActionKind.Refactor]`, or list out every kind provided, * such as `[CodeActionKind.Refactor.Extract.append('function'), CodeActionKind.Refactor.Extract.append('constant'), ...]`. */ - readonly providedCodeActionKinds?: ReadonlyArray; + readonly providedCodeActionKinds?: readonly CodeActionKind[]; /** * Static documentation for a class of code actions. * * Documentation from the provider is shown in the code actions menu if either: * - * - Code actions of `kind` are requested by VS Code. In this case, VS Code will show the documentation that + * - Code actions of `kind` are requested by the editor. In this case, the editor will show the documentation that * most closely matches the requested code action kind. For example, if a provider has documentation for * both `Refactor` and `RefactorExtract`, when the user requests code actions for `RefactorExtract`, - * VS Code will use the documentation for `RefactorExtract` instead of the documentation for `Refactor`. + * the editor will use the documentation for `RefactorExtract` instead of the documentation for `Refactor`. * * - Any code actions of `kind` are returned by the provider. * @@ -2372,23 +2384,23 @@ declare module 'vscode' { /** * Command that displays the documentation to the user. * - * This can display the documentation directly in VS Code or open a website using [`env.openExternal`](#env.openExternal); + * This can display the documentation directly in the editor or open a website using {@link env.openExternal `env.openExternal`}; * - * The title of this documentation code action is taken from [`Command.title`](#Command.title) + * The title of this documentation code action is taken from {@link Command.title `Command.title`} */ readonly command: Command; }>; } /** - * A code lens represents a [command](#Command) that should be shown along with + * A code lens represents a {@link Command} that should be shown along with * source text, like the number of references, a way to run tests, etc. * * A code lens is _unresolved_ when no command is associated to it. For performance * reasons the creation of a code lens and resolving should be done to two stages. * - * @see [CodeLensProvider.provideCodeLenses](#CodeLensProvider.provideCodeLenses) - * @see [CodeLensProvider.resolveCodeLens](#CodeLensProvider.resolveCodeLens) + * @see {@link CodeLensProvider.provideCodeLenses} + * @see {@link CodeLensProvider.resolveCodeLens} */ export class CodeLens { @@ -2417,7 +2429,7 @@ declare module 'vscode' { } /** - * A code lens provider adds [commands](#Command) to source text. The commands will be shown + * A code lens provider adds {@link Command commands} to source text. The commands will be shown * as dedicated horizontal lines in between the source text. */ export interface CodeLensProvider { @@ -2428,9 +2440,9 @@ declare module 'vscode' { onDidChangeCodeLenses?: Event; /** - * Compute a list of [lenses](#CodeLens). This call should return as fast as possible and if + * Compute a list of {@link CodeLens lenses}. This call should return as fast as possible and if * computing the commands is expensive implementors should only return code lens objects with the - * range set and implement [resolve](#CodeLensProvider.resolveCodeLens). + * range set and implement {@link CodeLensProvider.resolveCodeLens resolve}. * * @param document The document in which the command was invoked. * @param token A cancellation token. @@ -2441,7 +2453,7 @@ declare module 'vscode' { /** * This function will be called for each visible code lens, usually when scrolling and after - * calls to [compute](#CodeLensProvider.provideCodeLenses)-lenses. + * calls to {@link CodeLensProvider.provideCodeLenses compute}-lenses. * * @param codeLens Code lens that must be resolved. * @param token A cancellation token. @@ -2453,7 +2465,7 @@ declare module 'vscode' { /** * Information about where a symbol is defined. * - * Provides additional metadata over normal {@link Location location} definitions, including the range of + * Provides additional metadata over normal {@link Location} definitions, including the range of * the defining symbol */ export type DefinitionLink = LocationLink; @@ -2521,8 +2533,8 @@ declare module 'vscode' { } /** - * The declaration of a symbol representation as one or many [locations](#Location) - * or [location links](#LocationLink). + * The declaration of a symbol representation as one or many {@link Location locations} + * or {@link LocationLink location links}. */ export type Declaration = Location | Location[] | LocationLink[]; @@ -2548,7 +2560,7 @@ declare module 'vscode' { * The MarkdownString represents human-readable text that supports formatting via the * markdown syntax. Standard markdown is supported, also tables, but no embedded html. * - * When created with `supportThemeIcons` then rendering of [theme icons](#ThemeIcon) via + * When created with `supportThemeIcons` then rendering of {@link ThemeIcon theme icons} via * the `$()`-syntax is supported. */ export class MarkdownString { @@ -2565,7 +2577,7 @@ declare module 'vscode' { isTrusted?: boolean; /** - * Indicates that this markdown string can contain [ThemeIcons](#ThemeIcon), e.g. `$(zap)`. + * Indicates that this markdown string can contain {@link ThemeIcon ThemeIcons}, e.g. `$(zap)`. */ readonly supportThemeIcons?: boolean; @@ -2573,7 +2585,7 @@ declare module 'vscode' { * Creates a new markdown string with the given value. * * @param value Optional, initial value. - * @param supportThemeIcons Optional, Specifies whether [ThemeIcons](#ThemeIcon) are supported within the [`MarkdownString`](#MarkdownString). + * @param supportThemeIcons Optional, Specifies whether {@link ThemeIcon ThemeIcons} are supported within the {@link MarkdownString `MarkdownString`}. */ constructor(value?: string, supportThemeIcons?: boolean); @@ -2584,7 +2596,7 @@ declare module 'vscode' { appendText(value: string): MarkdownString; /** - * Appends the given string 'as is' to this markdown string. When [`supportThemeIcons`](#MarkdownString.supportThemeIcons) is `true`, [ThemeIcons](#ThemeIcon) in the `value` will be iconified. + * Appends the given string 'as is' to this markdown string. When {@link MarkdownString.supportThemeIcons `supportThemeIcons`} is `true`, {@link ThemeIcon ThemeIcons} in the `value` will be iconified. * @param value Markdown string. */ appendMarkdown(value: string): MarkdownString; @@ -2592,7 +2604,7 @@ declare module 'vscode' { /** * Appends the given string as codeblock using the provided language. * @param value A code snippet. - * @param language An optional [language identifier](#languages.getLanguages). + * @param language An optional {@link languages.getLanguages language identifier}. */ appendCodeblock(value: string, language?: string): MarkdownString; } @@ -2602,7 +2614,7 @@ declare module 'vscode' { * or a code-block that provides a language and a code snippet. Note that * markdown strings will be sanitized - that means html will be escaped. * - * @deprecated This type is deprecated, please use [`MarkdownString`](#MarkdownString) instead. + * @deprecated This type is deprecated, please use {@link MarkdownString `MarkdownString`} instead. */ export type MarkedString = MarkdownString | string | { language: string; value: string }; @@ -2684,13 +2696,13 @@ declare module 'vscode' { /** * The evaluatable expression provider interface defines the contract between extensions and * the debug hover. In this contract the provider returns an evaluatable expression for a given position - * in a document and VS Code evaluates this expression in the active debug session and shows the result in a debug hover. + * in a document and the editor evaluates this expression in the active debug session and shows the result in a debug hover. */ export interface EvaluatableExpressionProvider { /** * Provide an evaluatable expression for the given document and position. - * VS Code will evaluate this expression in the active debug session and will show the result in the debug hover. + * The editor will evaluate this expression in the active debug session and will show the result in the debug hover. * The expression can be implicitly specified by the range in the underlying document or by explicitly returning an expression. * * @param document The document for which the debug hover is about to appear. @@ -2811,7 +2823,7 @@ declare module 'vscode' { /** * An optional event to signal that inline values have changed. - * @see [EventEmitter](#EventEmitter) + * @see {@link EventEmitter} */ onDidChangeInlineValues?: Event | undefined; @@ -2864,7 +2876,7 @@ declare module 'vscode' { range: Range; /** - * The highlight kind, default is [text](#DocumentHighlightKind.Text). + * The highlight kind, default is {@link DocumentHighlightKind.Text text}. */ kind?: DocumentHighlightKind; @@ -2872,7 +2884,7 @@ declare module 'vscode' { * Creates a new document highlight object. * * @param range The range the highlight applies to. - * @param kind The highlight kind, default is [text](#DocumentHighlightKind.Text). + * @param kind The highlight kind, default is {@link DocumentHighlightKind.Text text}. */ constructor(range: Range, kind?: DocumentHighlightKind); } @@ -2963,7 +2975,7 @@ declare module 'vscode' { /** * Tags for this symbol. */ - tags?: ReadonlyArray; + tags?: readonly SymbolTag[]; /** * The location of this symbol. @@ -2983,7 +2995,7 @@ declare module 'vscode' { /** * Creates a new symbol information object. * - * @deprecated Please use the constructor taking a [location](#Location) object. + * @deprecated Please use the constructor taking a {@link Location} object. * * @param name The name of the symbol. * @param kind The kind of the symbol. @@ -3019,7 +3031,7 @@ declare module 'vscode' { /** * Tags for this symbol. */ - tags?: ReadonlyArray; + tags?: readonly SymbolTag[]; /** * The range enclosing this symbol not including leading/trailing whitespace but everything else, e.g. comments and code. @@ -3028,7 +3040,7 @@ declare module 'vscode' { /** * The range that should be selected and reveal when this symbol is being picked, e.g. the name of a function. - * Must be contained by the [`range`](#DocumentSymbol.range). + * Must be contained by the {@link DocumentSymbol.range `range`}. */ selectionRange: Range; @@ -3091,7 +3103,7 @@ declare module 'vscode' { * strict matching. * * To improve performance implementors can implement `resolveWorkspaceSymbol` and then provide symbols with partial - * [location](#SymbolInformation.location)-objects, without a `range` defined. The editor will then call + * {@link SymbolInformation.location location}-objects, without a `range` defined. The editor will then call * `resolveWorkspaceSymbol` for selected symbols only, e.g. when opening a workspace symbol. * * @param query A query string, can be the empty string in which case all symbols should be returned. @@ -3102,9 +3114,9 @@ declare module 'vscode' { provideWorkspaceSymbols(query: string, token: CancellationToken): ProviderResult; /** - * Given a symbol fill in its [location](#SymbolInformation.location). This method is called whenever a symbol + * Given a symbol fill in its {@link SymbolInformation.location location}. This method is called whenever a symbol * is selected in the UI. Providers can implement this method and return incomplete symbols from - * [`provideWorkspaceSymbols`](#WorkspaceSymbolProvider.provideWorkspaceSymbols) which often helps to improve + * {@link WorkspaceSymbolProvider.provideWorkspaceSymbols `provideWorkspaceSymbols`} which often helps to improve * performance. * * @param symbol The symbol that is to be resolved. Guaranteed to be an instance of an object returned from an @@ -3237,7 +3249,7 @@ declare module 'vscode' { description?: string; /** - * The icon path or [ThemeIcon](#ThemeIcon) for the edit. + * The icon path or {@link ThemeIcon} for the edit. */ iconPath?: Uri | { light: Uri; dark: Uri } | ThemeIcon; } @@ -3246,7 +3258,7 @@ declare module 'vscode' { * A workspace edit is a collection of textual and files changes for * multiple resources and documents. * - * Use the [applyEdit](#workspace.applyEdit)-function to apply a workspace edit. + * Use the {@link workspace.applyEdit applyEdit}-function to apply a workspace edit. */ export class WorkspaceEdit { @@ -3368,7 +3380,7 @@ declare module 'vscode' { /** * Builder-function that appends the given string to - * the [`value`](#SnippetString.value) of this snippet string. + * the {@link SnippetString.value `value`} of this snippet string. * * @param string A value to append 'as given'. The string will be escaped. * @return This snippet string. @@ -3377,7 +3389,7 @@ declare module 'vscode' { /** * Builder-function that appends a tabstop (`$1`, `$2` etc) to - * the [`value`](#SnippetString.value) of this snippet string. + * the {@link SnippetString.value `value`} of this snippet string. * * @param number The number of this tabstop, defaults to an auto-increment * value starting at 1. @@ -3387,7 +3399,7 @@ declare module 'vscode' { /** * Builder-function that appends a placeholder (`${1:value}`) to - * the [`value`](#SnippetString.value) of this snippet string. + * the {@link SnippetString.value `value`} of this snippet string. * * @param value The value of this placeholder - either a string or a function * with which a nested snippet can be created. @@ -3399,7 +3411,7 @@ declare module 'vscode' { /** * Builder-function that appends a choice (`${1|a,b,c|}`) to - * the [`value`](#SnippetString.value) of this snippet string. + * the {@link SnippetString.value `value`} of this snippet string. * * @param values The values for choices - the array of strings * @param number The number of this tabstop, defaults to an auto-increment @@ -3410,7 +3422,7 @@ declare module 'vscode' { /** * Builder-function that appends a variable (`${VAR}`) to - * the [`value`](#SnippetString.value) of this snippet string. + * the {@link SnippetString.value `value`} of this snippet string. * * @param name The name of the variable - excluding the `$`. * @param defaultValue The default value which is used when the variable name cannot @@ -3508,8 +3520,8 @@ declare module 'vscode' { /** * Represents semantic tokens, either in a range or in an entire document. - * @see [provideDocumentSemanticTokens](#DocumentSemanticTokensProvider.provideDocumentSemanticTokens) for an explanation of the format. - * @see [SemanticTokensBuilder](#SemanticTokensBuilder) for a helper to create an instance. + * @see {@link DocumentSemanticTokensProvider.provideDocumentSemanticTokens provideDocumentSemanticTokens} for an explanation of the format. + * @see {@link SemanticTokensBuilder} for a helper to create an instance. */ export class SemanticTokens { /** @@ -3520,7 +3532,7 @@ declare module 'vscode' { readonly resultId?: string; /** * The actual tokens data. - * @see [provideDocumentSemanticTokens](#DocumentSemanticTokensProvider.provideDocumentSemanticTokens) for an explanation of the format. + * @see {@link DocumentSemanticTokensProvider.provideDocumentSemanticTokens provideDocumentSemanticTokens} for an explanation of the format. */ readonly data: Uint32Array; @@ -3529,7 +3541,7 @@ declare module 'vscode' { /** * Represents edits to semantic tokens. - * @see [provideDocumentSemanticTokensEdits](#DocumentSemanticTokensProvider.provideDocumentSemanticTokensEdits) for an explanation of the format. + * @see {@link DocumentSemanticTokensProvider.provideDocumentSemanticTokensEdits provideDocumentSemanticTokensEdits} for an explanation of the format. */ export class SemanticTokensEdits { /** @@ -3549,7 +3561,7 @@ declare module 'vscode' { /** * Represents an edit to semantic tokens. - * @see [provideDocumentSemanticTokensEdits](#DocumentSemanticTokensProvider.provideDocumentSemanticTokensEdits) for an explanation of the format. + * @see {@link DocumentSemanticTokensProvider.provideDocumentSemanticTokensEdits provideDocumentSemanticTokensEdits} for an explanation of the format. */ export class SemanticTokensEdit { /** @@ -3633,7 +3645,7 @@ declare module 'vscode' { * [ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ] * ``` * - * @see [SemanticTokensBuilder](#SemanticTokensBuilder) for a helper to encode tokens as integers. + * @see {@link SemanticTokensBuilder} for a helper to encode tokens as integers. * *NOTE*: When doing edits, it is possible that multiple edits occur until VS Code decides to invoke the semantic tokens provider. * *NOTE*: If the provider cannot temporarily compute semantic tokens, it can indicate this by throwing an error with the message 'Busy'. */ @@ -3677,7 +3689,7 @@ declare module 'vscode' { */ export interface DocumentRangeSemanticTokensProvider { /** - * @see [provideDocumentSemanticTokens](#DocumentSemanticTokensProvider.provideDocumentSemanticTokens). + * @see {@link DocumentSemanticTokensProvider.provideDocumentSemanticTokens provideDocumentSemanticTokens}. */ provideDocumentRangeSemanticTokens(document: TextDocument, range: Range, token: CancellationToken): ProviderResult; } @@ -3778,8 +3790,8 @@ declare module 'vscode' { * The label of this signature. * * Either a string or inclusive start and exclusive end offsets within its containing - * [signature label](#SignatureInformation.label). *Note*: A label of type string must be - * a substring of its containing signature information's [label](#SignatureInformation.label). + * {@link SignatureInformation.label signature label}. *Note*: A label of type string must be + * a substring of its containing signature information's {@link SignatureInformation.label label}. */ label: string | [number, number]; @@ -3825,7 +3837,7 @@ declare module 'vscode' { /** * The index of the active parameter. * - * If provided, this is used in place of [`SignatureHelp.activeSignature`](#SignatureHelp.activeSignature). + * If provided, this is used in place of {@link SignatureHelp.activeSignature `SignatureHelp.activeSignature`}. */ activeParameter?: number; @@ -3862,7 +3874,7 @@ declare module 'vscode' { } /** - * How a [`SignatureHelpProvider`](#SignatureHelpProvider) was triggered. + * How a {@link SignatureHelpProvider `SignatureHelpProvider`} was triggered. */ export enum SignatureHelpTriggerKind { /** @@ -3883,7 +3895,7 @@ declare module 'vscode' { /** * Additional information about the context in which a - * [`SignatureHelpProvider`](#SignatureHelpProvider.provideSignatureHelp) was triggered. + * {@link SignatureHelpProvider.provideSignatureHelp `SignatureHelpProvider`} was triggered. */ export interface SignatureHelpContext { /** @@ -3908,7 +3920,7 @@ declare module 'vscode' { readonly isRetrigger: boolean; /** - * The currently active [`SignatureHelp`](#SignatureHelp). + * The currently active {@link SignatureHelp `SignatureHelp`}. * * The `activeSignatureHelp` has its [`SignatureHelp.activeSignature`] field updated based on * the user arrowing through available signatures. @@ -3937,13 +3949,13 @@ declare module 'vscode' { } /** - * Metadata about a registered [`SignatureHelpProvider`](#SignatureHelpProvider). + * Metadata about a registered {@link SignatureHelpProvider `SignatureHelpProvider`}. */ export interface SignatureHelpProviderMetadata { /** * List of characters that trigger signature help. */ - readonly triggerCharacters: ReadonlyArray; + readonly triggerCharacters: readonly string[]; /** * List of characters that re-trigger signature help. @@ -3951,7 +3963,7 @@ declare module 'vscode' { * These trigger characters are only active when signature help is already showing. All trigger characters * are also counted as re-trigger characters. */ - readonly retriggerCharacters: ReadonlyArray; + readonly retriggerCharacters: readonly string[]; } /** @@ -4001,17 +4013,17 @@ declare module 'vscode' { /** * A completion item represents a text snippet that is proposed to complete text that is being typed. * - * It is sufficient to create a completion item from just a [label](#CompletionItem.label). In that - * case the completion item will replace the [word](#TextDocument.getWordRangeAtPosition) - * until the cursor with the given label or [insertText](#CompletionItem.insertText). Otherwise the - * given [edit](#CompletionItem.textEdit) is used. + * It is sufficient to create a completion item from just a {@link CompletionItem.label label}. In that + * case the completion item will replace the {@link TextDocument.getWordRangeAtPosition word} + * until the cursor with the given label or {@link CompletionItem.insertText insertText}. Otherwise the + * given {@link CompletionItem.textEdit edit} is used. * * When selecting a completion item in the editor its defined or synthesized text edit will be applied - * to *all* cursors/selections whereas [additionalTextEdits](#CompletionItem.additionalTextEdits) will be + * to *all* cursors/selections whereas {@link CompletionItem.additionalTextEdits additionalTextEdits} will be * applied as provided. * - * @see [CompletionItemProvider.provideCompletionItems](#CompletionItemProvider.provideCompletionItems) - * @see [CompletionItemProvider.resolveCompletionItem](#CompletionItemProvider.resolveCompletionItem) + * @see {@link CompletionItemProvider.provideCompletionItems} + * @see {@link CompletionItemProvider.resolveCompletionItem} */ export class CompletionItem { @@ -4031,7 +4043,7 @@ declare module 'vscode' { /** * Tags for this completion item. */ - tags?: ReadonlyArray; + tags?: readonly CompletionItemTag[]; /** * A human-readable string with additional information @@ -4046,25 +4058,25 @@ declare module 'vscode' { /** * A string that should be used when comparing this item - * with other items. When `falsy` the [label](#CompletionItem.label) + * with other items. When `falsy` the {@link CompletionItem.label label} * is used. * * Note that `sortText` is only used for the initial ordering of completion * items. When having a leading word (prefix) ordering is based on how * well completions match that prefix and the initial ordering is only used * when completions match equally well. The prefix is defined by the - * [`range`](#CompletionItem.range)-property and can therefore be different + * {@link CompletionItem.range `range`}-property and can therefore be different * for each completion. */ sortText?: string; /** * A string that should be used when filtering a set of - * completion items. When `falsy` the [label](#CompletionItem.label) + * completion items. When `falsy` the {@link CompletionItem.label label} * is used. * * Note that the filter text is matched against the leading word (prefix) which is defined - * by the [`range`](#CompletionItem.range)-property. + * by the {@link CompletionItem.range `range`}-property. */ filterText?: string; @@ -4077,7 +4089,7 @@ declare module 'vscode' { /** * A string or snippet that should be inserted in a document when selecting - * this completion. When `falsy` the [label](#CompletionItem.label) + * this completion. When `falsy` the {@link CompletionItem.label label} * is used. */ insertText?: string | SnippetString; @@ -4085,12 +4097,12 @@ declare module 'vscode' { /** * A range or a insert and replace range selecting the text that should be replaced by this completion item. * - * When omitted, the range of the [current word](#TextDocument.getWordRangeAtPosition) is used as replace-range - * and as insert-range the start of the [current word](#TextDocument.getWordRangeAtPosition) to the + * When omitted, the range of the {@link TextDocument.getWordRangeAtPosition current word} is used as replace-range + * and as insert-range the start of the {@link TextDocument.getWordRangeAtPosition current word} to the * current position is used. * - * *Note 1:* A range must be a [single line](#Range.isSingleLine) and it must - * [contain](#Range.contains) the position at which completion has been [requested](#CompletionItemProvider.provideCompletionItems). + * *Note 1:* A range must be a {@link Range.isSingleLine single line} and it must + * {@link Range.contains contain} the position at which completion has been {@link CompletionItemProvider.provideCompletionItems requested}. * *Note 2:* A insert range must be a prefix of a replace range, that means it must be contained and starting at the same position. */ range?: Range | { inserting: Range; replacing: Range; }; @@ -4103,7 +4115,7 @@ declare module 'vscode' { commitCharacters?: string[]; /** - * Keep whitespace of the [insertText](#CompletionItem.insertText) as is. By default, the editor adjusts leading + * Keep whitespace of the {@link CompletionItem.insertText insertText} as is. By default, the editor adjusts leading * whitespace of new lines so that they match the indentation of the line for which the item is accepted - setting * this to `true` will prevent that. */ @@ -4112,43 +4124,43 @@ declare module 'vscode' { /** * @deprecated Use `CompletionItem.insertText` and `CompletionItem.range` instead. * - * An [edit](#TextEdit) which is applied to a document when selecting + * An {@link TextEdit edit} which is applied to a document when selecting * this completion. When an edit is provided the value of - * [insertText](#CompletionItem.insertText) is ignored. + * {@link CompletionItem.insertText insertText} is ignored. * - * The [range](#Range) of the edit must be single-line and on the same - * line completions were [requested](#CompletionItemProvider.provideCompletionItems) at. + * The {@link Range} of the edit must be single-line and on the same + * line completions were {@link CompletionItemProvider.provideCompletionItems requested} at. */ textEdit?: TextEdit; /** - * An optional array of additional [text edits](#TextEdit) that are applied when - * selecting this completion. Edits must not overlap with the main [edit](#CompletionItem.textEdit) + * An optional array of additional {@link TextEdit text edits} that are applied when + * selecting this completion. Edits must not overlap with the main {@link CompletionItem.textEdit edit} * nor with themselves. */ additionalTextEdits?: TextEdit[]; /** - * An optional [command](#Command) that is executed *after* inserting this completion. *Note* that + * An optional {@link Command} that is executed *after* inserting this completion. *Note* that * additional modifications to the current document should be described with the - * [additionalTextEdits](#CompletionItem.additionalTextEdits)-property. + * {@link CompletionItem.additionalTextEdits additionalTextEdits}-property. */ command?: Command; /** * Creates a new completion item. * - * Completion items must have at least a [label](#CompletionItem.label) which then + * Completion items must have at least a {@link CompletionItem.label label} which then * will be used as insert text as well as for sorting and filtering. * * @param label The label of the completion. - * @param kind The [kind](#CompletionItemKind) of the completion. + * @param kind The {@link CompletionItemKind kind} of the completion. */ constructor(label: string, kind?: CompletionItemKind); } /** - * Represents a collection of [completion items](#CompletionItem) to be presented + * Represents a collection of {@link CompletionItem completion items} to be presented * in the editor. */ export class CompletionList { @@ -4174,7 +4186,7 @@ declare module 'vscode' { } /** - * How a [completion provider](#CompletionItemProvider) was triggered + * How a {@link CompletionItemProvider completion provider} was triggered */ export enum CompletionTriggerKind { /** @@ -4193,7 +4205,7 @@ declare module 'vscode' { /** * Contains additional information about the context in which - * [completion provider](#CompletionItemProvider.provideCompletionItems) is triggered. + * {@link CompletionItemProvider.provideCompletionItems completion provider} is triggered. */ export interface CompletionContext { /** @@ -4215,9 +4227,9 @@ declare module 'vscode' { * The completion item provider interface defines the contract between extensions and * [IntelliSense](https://code.visualstudio.com/docs/editor/intellisense). * - * Providers can delay the computation of the [`detail`](#CompletionItem.detail) - * and [`documentation`](#CompletionItem.documentation) properties by implementing the - * [`resolveCompletionItem`](#CompletionItemProvider.resolveCompletionItem)-function. However, properties that + * Providers can delay the computation of the {@link CompletionItem.detail `detail`} + * and {@link CompletionItem.documentation `documentation`} properties by implementing the + * {@link CompletionItemProvider.resolveCompletionItem `resolveCompletionItem`}-function. However, properties that * are needed for the initial sorting and filtering, like `sortText`, `filterText`, `insertText`, and `range`, must * not be changed during resolve. * @@ -4234,22 +4246,22 @@ declare module 'vscode' { * @param token A cancellation token. * @param context How the completion was triggered. * - * @return An array of completions, a [completion list](#CompletionList), or a thenable that resolves to either. + * @return An array of completions, a {@link CompletionList completion list}, or a thenable that resolves to either. * The lack of a result can be signaled by returning `undefined`, `null`, or an empty array. */ provideCompletionItems(document: TextDocument, position: Position, token: CancellationToken, context: CompletionContext): ProviderResult>; /** - * Given a completion item fill in more data, like [doc-comment](#CompletionItem.documentation) - * or [details](#CompletionItem.detail). + * Given a completion item fill in more data, like {@link CompletionItem.documentation doc-comment} + * or {@link CompletionItem.detail details}. * * The editor will only resolve a completion item once. * * *Note* that this function is called when completion items are already showing in the UI or when an item has been * selected for insertion. Because of that, no property that changes the presentation (label, sorting, filtering etc) - * or the (primary) insert behaviour ([insertText](#CompletionItem.insertText)) can be changed. + * or the (primary) insert behaviour ({@link CompletionItem.insertText insertText}) can be changed. * - * This function may fill in [additionalTextEdits](#CompletionItem.additionalTextEdits). However, that means an item might be + * This function may fill in {@link CompletionItem.additionalTextEdits additionalTextEdits}. However, that means an item might be * inserted *before* resolving is done and in that case the editor will do a best effort to still apply those additional * text edits. * @@ -4307,15 +4319,15 @@ declare module 'vscode' { * * @param document The document in which the command was invoked. * @param token A cancellation token. - * @return An array of [document links](#DocumentLink) or a thenable that resolves to such. The lack of a result + * @return An array of {@link DocumentLink document links} or a thenable that resolves to such. The lack of a result * can be signaled by returning `undefined`, `null`, or an empty array. */ provideDocumentLinks(document: TextDocument, token: CancellationToken): ProviderResult; /** - * Given a link fill in its [target](#DocumentLink.target). This method is called when an incomplete + * Given a link fill in its {@link DocumentLink.target target}. This method is called when an incomplete * link is selected in the UI. Providers can implement this method and return incomplete links - * (without target) from the [`provideDocumentLinks`](#DocumentLinkProvider.provideDocumentLinks) method which + * (without target) from the {@link DocumentLinkProvider.provideDocumentLinks `provideDocumentLinks`} method which * often helps to improve performance. * * @param link The link that is to be resolved. @@ -4386,7 +4398,7 @@ declare module 'vscode' { } /** - * A color presentation object describes how a [`color`](#Color) should be represented as text and what + * A color presentation object describes how a {@link Color `color`} should be represented as text and what * edits are required to refer to it from source code. * * For some languages one color can have multiple presentations, e.g. css can represent the color red with @@ -4403,15 +4415,15 @@ declare module 'vscode' { label: string; /** - * An [edit](#TextEdit) which is applied to a document when selecting - * this presentation for the color. When `falsy` the [label](#ColorPresentation.label) + * An {@link TextEdit edit} which is applied to a document when selecting + * this presentation for the color. When `falsy` the {@link ColorPresentation.label label} * is used. */ textEdit?: TextEdit; /** - * An optional array of additional [text edits](#TextEdit) that are applied when - * selecting this color presentation. Edits must not overlap with the main [edit](#ColorPresentation.textEdit) nor with themselves. + * An optional array of additional {@link TextEdit text edits} that are applied when + * selecting this color presentation. Edits must not overlap with the main {@link ColorPresentation.textEdit edit} nor with themselves. */ additionalTextEdits?: TextEdit[]; @@ -4434,13 +4446,13 @@ declare module 'vscode' { * * @param document The document in which the command was invoked. * @param token A cancellation token. - * @return An array of [color information](#ColorInformation) or a thenable that resolves to such. The lack of a result + * @return An array of {@link ColorInformation color information} or a thenable that resolves to such. The lack of a result * can be signaled by returning `undefined`, `null`, or an empty array. */ provideDocumentColors(document: TextDocument, token: CancellationToken): ProviderResult; /** - * Provide [representations](#ColorPresentation) for a color. + * Provide {@link ColorPresentation representations} for a color. * * @param color The color to show and insert. * @param context A context object with additional information @@ -4470,10 +4482,10 @@ declare module 'vscode' { end: number; /** - * Describes the [Kind](#FoldingRangeKind) of the folding range such as [Comment](#FoldingRangeKind.Comment) or - * [Region](#FoldingRangeKind.Region). The kind is used to categorize folding ranges and used by commands + * Describes the {@link FoldingRangeKind Kind} of the folding range such as {@link FoldingRangeKind.Comment Comment} or + * {@link FoldingRangeKind.Region Region}. The kind is used to categorize folding ranges and used by commands * like 'Fold all comments'. See - * [FoldingRangeKind](#FoldingRangeKind) for an enumeration of all kinds. + * {@link FoldingRangeKind} for an enumeration of all kinds. * If not set, the range is originated from a syntax element. */ kind?: FoldingRangeKind; @@ -4489,7 +4501,7 @@ declare module 'vscode' { } /** - * An enumeration of specific folding range kinds. The kind is an optional field of a [FoldingRange](#FoldingRange) + * An enumeration of specific folding range kinds. The kind is an optional field of a {@link FoldingRange} * and is used to distinguish specific folding ranges such as ranges originated from comments. The kind is used by commands like * `Fold all comments` or `Fold all regions`. * If the kind is not set on the range, the range originated from a syntax element other than comments, imports or region markers. @@ -4543,7 +4555,7 @@ declare module 'vscode' { export class SelectionRange { /** - * The [range](#Range) of this selection range. + * The {@link Range} of this selection range. */ range: Range; @@ -4567,7 +4579,7 @@ declare module 'vscode' { * * Selection ranges should be computed individually and independent for each position. The editor will merge * and deduplicate ranges but providers must return hierarchies of selection ranges so that a range - * is [contained](#Range.contains) by its parent. + * is {@link Range.contains contained} by its parent. * * @param document The document in which the command was invoked. * @param positions The positions at which the command was invoked. @@ -4596,7 +4608,7 @@ declare module 'vscode' { /** * Tags for this item. */ - tags?: ReadonlyArray; + tags?: readonly SymbolTag[]; /** * More detail for this item, e.g. the signature of a function. @@ -4615,7 +4627,7 @@ declare module 'vscode' { /** * The range that should be selected and revealed when this symbol is being picked, e.g. the name of a function. - * Must be contained by the [`range`](#CallHierarchyItem.range). + * Must be contained by the {@link CallHierarchyItem.range `range`}. */ selectionRange: Range; @@ -4637,7 +4649,7 @@ declare module 'vscode' { /** * The range at which at which the calls appears. This is relative to the caller - * denoted by [`this.from`](#CallHierarchyIncomingCall.from). + * denoted by {@link CallHierarchyIncomingCall.from `this.from`}. */ fromRanges: Range[]; @@ -4662,8 +4674,8 @@ declare module 'vscode' { /** * The range at which this item is called. This is the range relative to the caller, e.g the item - * passed to [`provideCallHierarchyOutgoingCalls`](#CallHierarchyProvider.provideCallHierarchyOutgoingCalls) - * and not [`this.to`](#CallHierarchyOutgoingCall.to). + * passed to {@link CallHierarchyProvider.provideCallHierarchyOutgoingCalls `provideCallHierarchyOutgoingCalls`} + * and not {@link CallHierarchyOutgoingCall.to `this.to`}. */ fromRanges: Range[]; @@ -4970,10 +4982,10 @@ declare module 'vscode' { * - *Default Settings* * - *Global (User) Settings* * - *Workspace settings* - * - *Workspace Folder settings* - From one of the [Workspace Folders](#workspace.workspaceFolders) under which requested resource belongs to. + * - *Workspace Folder settings* - From one of the {@link workspace.workspaceFolders Workspace Folders} under which requested resource belongs to. * - *Language settings* - Settings defined under requested language. * - * The *effective* value (returned by [`get`](#WorkspaceConfiguration.get)) is computed by overriding or merging the values in the following order. + * The *effective* value (returned by {@link WorkspaceConfiguration.get `get`}) is computed by overriding or merging the values in the following order. * * ``` * `defaultValue` (if defined in `package.json` otherwise derived from the value's type) @@ -5059,7 +5071,7 @@ declare module 'vscode' { * Retrieve all information about a configuration setting. A configuration value * often consists of a *default* value, a global or installation-wide value, * a workspace-specific value, folder-specific value - * and language-specific values (if [WorkspaceConfiguration](#WorkspaceConfiguration) is scoped to a language). + * and language-specific values (if {@link WorkspaceConfiguration} is scoped to a language). * * Also provides all language ids under which the given configuration setting is defined. * @@ -5091,20 +5103,20 @@ declare module 'vscode' { * * A value can be changed in * - * - [Global settings](#ConfigurationTarget.Global): Changes the value for all instances of the editor. - * - [Workspace settings](#ConfigurationTarget.Workspace): Changes the value for current workspace, if available. - * - [Workspace folder settings](#ConfigurationTarget.WorkspaceFolder): Changes the value for settings from one of the [Workspace Folders](#workspace.workspaceFolders) under which the requested resource belongs to. + * - {@link ConfigurationTarget.Global Global settings}: Changes the value for all instances of the editor. + * - {@link ConfigurationTarget.Workspace Workspace settings}: Changes the value for current workspace, if available. + * - {@link ConfigurationTarget.WorkspaceFolder Workspace folder settings}: Changes the value for settings from one of the {@link workspace.workspaceFolders Workspace Folders} under which the requested resource belongs to. * - Language settings: Changes the value for the requested languageId. * * *Note:* To remove a configuration value use `undefined`, like so: `config.update('somekey', undefined)` * * @param section Configuration name, supports _dotted_ names. * @param value The new value. - * @param configurationTarget The [configuration target](#ConfigurationTarget) or a boolean value. - * - If `true` updates [Global settings](#ConfigurationTarget.Global). - * - If `false` updates [Workspace settings](#ConfigurationTarget.Workspace). - * - If `undefined` or `null` updates to [Workspace folder settings](#ConfigurationTarget.WorkspaceFolder) if configuration is resource specific, - * otherwise to [Workspace settings](#ConfigurationTarget.Workspace). + * @param configurationTarget The {@link ConfigurationTarget configuration target} or a boolean value. + * - If `true` updates {@link ConfigurationTarget.Global Global settings}. + * - If `false` updates {@link ConfigurationTarget.Workspace Workspace settings}. + * - If `undefined` or `null` updates to {@link ConfigurationTarget.WorkspaceFolder Workspace folder settings} if configuration is resource specific, + * otherwise to {@link ConfigurationTarget.Workspace Workspace settings}. * @param overrideInLanguage Whether to update the value in the scope of requested languageId or not. * - If `true` updates the value under the requested languageId. * - If `undefined` updates the value under the requested languageId only if the configuration is defined for the language. @@ -5113,7 +5125,7 @@ declare module 'vscode' { * - window configuration to workspace folder * - configuration to workspace or workspace folder when no workspace is opened. * - configuration to workspace folder when there is no workspace folder settings. - * - configuration to workspace folder when [WorkspaceConfiguration](#WorkspaceConfiguration) is not scoped to a resource. + * - configuration to workspace folder when {@link WorkspaceConfiguration} is not scoped to a resource. */ update(section: string, value: any, configurationTarget?: ConfigurationTarget | boolean, overrideInLanguage?: boolean): Thenable; @@ -5149,7 +5161,7 @@ declare module 'vscode' { } /** - * Represents the connection of two locations. Provides additional metadata over normal [locations](#Location), + * Represents the connection of two locations. Provides additional metadata over normal {@link Location locations}, * including an origin range. */ export interface LocationLink { @@ -5185,7 +5197,7 @@ declare module 'vscode' { /** * An array of resources for which diagnostics have changed. */ - readonly uris: ReadonlyArray; + readonly uris: readonly Uri[]; } /** @@ -5282,7 +5294,7 @@ declare module 'vscode' { message: string; /** - * The severity, default is [error](#DiagnosticSeverity.Error). + * The severity, default is {@link DiagnosticSeverity.Error error}. */ severity: DiagnosticSeverity; @@ -5294,12 +5306,12 @@ declare module 'vscode' { /** * A code or identifier for this diagnostic. - * Should be used for later processing, e.g. when providing [code actions](#CodeActionContext). + * Should be used for later processing, e.g. when providing {@link CodeActionContext code actions}. */ code?: string | number | { /** * A code or identifier for this diagnostic. - * Should be used for later processing, e.g. when providing [code actions](#CodeActionContext). + * Should be used for later processing, e.g. when providing {@link CodeActionContext code actions}. */ value: string | number; @@ -5325,18 +5337,18 @@ declare module 'vscode' { * * @param range The range to which this diagnostic applies. * @param message The human-readable message. - * @param severity The severity, default is [error](#DiagnosticSeverity.Error). + * @param severity The severity, default is {@link DiagnosticSeverity.Error error}. */ constructor(range: Range, message: string, severity?: DiagnosticSeverity); } /** * A diagnostics collection is a container that manages a set of - * [diagnostics](#Diagnostic). Diagnostics are always scopes to a + * {@link Diagnostic diagnostics}. Diagnostics are always scopes to a * diagnostics collection and a resource. * * To get an instance of a `DiagnosticCollection` use - * [createDiagnosticCollection](#languages.createDiagnosticCollection). + * {@link languages.createDiagnosticCollection createDiagnosticCollection}. */ export interface DiagnosticCollection { @@ -5354,7 +5366,7 @@ declare module 'vscode' { * @param uri A resource identifier. * @param diagnostics Array of diagnostics or `undefined` */ - set(uri: Uri, diagnostics: ReadonlyArray | undefined): void; + set(uri: Uri, diagnostics: readonly Diagnostic[] | undefined): void; /** * Replace diagnostics for multiple resources in this collection. @@ -5366,7 +5378,7 @@ declare module 'vscode' { * * @param entries An array of tuples, like `[[file1, [d1, d2]], [file2, [d3, d4, d5]]]`, or `undefined`. */ - set(entries: ReadonlyArray<[Uri, ReadonlyArray | undefined]>): void; + set(entries: ReadonlyArray<[Uri, readonly Diagnostic[] | undefined]>): void; /** * Remove all diagnostics from this collection that belong @@ -5388,16 +5400,16 @@ declare module 'vscode' { * @param callback Function to execute for each entry. * @param thisArg The `this` context used when invoking the handler function. */ - forEach(callback: (uri: Uri, diagnostics: ReadonlyArray, collection: DiagnosticCollection) => any, thisArg?: any): void; + forEach(callback: (uri: Uri, diagnostics: readonly Diagnostic[], collection: DiagnosticCollection) => any, thisArg?: any): void; /** * Get the diagnostics for a given resource. *Note* that you cannot * modify the diagnostics-array returned from this call. * * @param uri A resource identifier. - * @returns An immutable array of [diagnostics](#Diagnostic) or `undefined`. + * @returns An immutable array of {@link Diagnostic diagnostics} or `undefined`. */ - get(uri: Uri): ReadonlyArray | undefined; + get(uri: Uri): readonly Diagnostic[] | undefined; /** * Check if this collection contains diagnostics for a @@ -5410,7 +5422,7 @@ declare module 'vscode' { /** * Dispose and free associated resources. Calls - * [clear](#DiagnosticCollection.clear). + * {@link DiagnosticCollection.clear clear}. */ dispose(): void; } @@ -5423,13 +5435,13 @@ declare module 'vscode' { export enum ViewColumn { /** * A *symbolic* editor column representing the currently active column. This value - * can be used when opening editors, but the *resolved* [viewColumn](#TextEditor.viewColumn)-value + * can be used when opening editors, but the *resolved* {@link TextEditor.viewColumn viewColumn}-value * of editors will always be `One`, `Two`, `Three`,... or `undefined` but never `Active`. */ Active = -1, /** * A *symbolic* editor column representing the column to the side of the active one. This value - * can be used when opening editors, but the *resolved* [viewColumn](#TextEditor.viewColumn)-value + * can be used when opening editors, but the *resolved* {@link TextEditor.viewColumn viewColumn}-value * of editors will always be `One`, `Two`, `Three`,... or `undefined` but never `Beside`. */ Beside = -2, @@ -5475,7 +5487,7 @@ declare module 'vscode' { * An output channel is a container for readonly textual information. * * To get an instance of an `OutputChannel` use - * [createOutputChannel](#window.createOutputChannel). + * {@link window.createOutputChannel createOutputChannel}. */ export interface OutputChannel { @@ -5572,6 +5584,14 @@ declare module 'vscode' { */ export interface StatusBarItem { + /** + * The identifier of this item. + * + * *Note*: if no identifier was provided by the {@link window.createStatusBarItem `window.createStatusBarItem`} + * method, the identifier will match the {@link Extension.id extension identifier}. + */ + readonly id: string; + /** * The alignment of this item. */ @@ -5583,6 +5603,13 @@ declare module 'vscode' { */ readonly priority?: number; + /** + * The name of the entry, like 'Python Language Indicator', 'Git Status' etc. + * Try to keep the length of the name short, yet descriptive enough that + * users can understand what the status bar item is about. + */ + name: string | undefined; + /** * The text to show for the entry. You can embed icons in the text by leveraging the syntax: * @@ -5616,17 +5643,17 @@ declare module 'vscode' { backgroundColor: ThemeColor | undefined; /** - * [`Command`](#Command) or identifier of a command to run on click. + * {@link Command `Command`} or identifier of a command to run on click. * - * The command must be [known](#commands.getCommands). + * The command must be {@link commands.getCommands known}. * - * Note that if this is a [`Command`](#Command) object, only the [`command`](#Command.command) and [`arguments`](#Command.arguments) + * Note that if this is a {@link Command `Command`} object, only the {@link Command.command `command`} and {@link Command.arguments `arguments`} * are used by VS Code. */ command: string | Command | undefined; /** - * Accessibility information used when screen reader interacts with this StatusBar item + * Accessibility information used when a screen reader interacts with this StatusBar item */ accessibilityInformation?: AccessibilityInformation; @@ -5642,7 +5669,7 @@ declare module 'vscode' { /** * Dispose and free associated resources. Call - * [hide](#StatusBarItem.hide). + * {@link StatusBarItem.hide hide}. */ dispose(): void; } @@ -5767,12 +5794,12 @@ declare module 'vscode' { */ export interface TerminalLink { /** - * The start index of the link on [TerminalLinkContext.line](#TerminalLinkContext.line]. + * The start index of the link on {@link TerminalLinkContext.line}. */ startIndex: number; /** - * The length of the link on [TerminalLinkContext.line](#TerminalLinkContext.line] + * The length of the link on {@link TerminalLinkContext.line}. */ length: number; @@ -5833,7 +5860,7 @@ declare module 'vscode' { * * *Note* that this event should be used to propagate information about children. * - * @see [EventEmitter](#EventEmitter) + * @see {@link EventEmitter} */ onDidChangeFileDecorations?: Event; @@ -5842,7 +5869,7 @@ declare module 'vscode' { * * *Note* that this function is only called when a file gets rendered in the UI. * This means a decoration from a descendent that propagates upwards must be signaled - * to the editor via the [onDidChangeFileDecorations](#FileDecorationProvider.onDidChangeFileDecorations)-event. + * to the editor via the {@link FileDecorationProvider.onDidChangeFileDecorations onDidChangeFileDecorations}-event. * * @param uri The uri of the file to provide a decoration for. * @param token A cancellation token. @@ -5872,7 +5899,7 @@ declare module 'vscode' { /** * Represents an extension. * - * To get an instance of an `Extension` use [getExtension](#extensions.getExtension). + * To get an instance of an `Extension` use {@link extensions.getExtension getExtension}. */ export interface Extension { @@ -5888,7 +5915,7 @@ declare module 'vscode' { /** * The absolute file path of the directory containing this extension. Shorthand - * notation for [Extension.extensionUri.fsPath](#Extension.extensionUri) (independent of the uri scheme). + * notation for {@link Extension.extensionUri Extension.extensionUri.fsPath} (independent of the uri scheme). */ readonly extensionPath: string; @@ -5907,7 +5934,7 @@ declare module 'vscode' { * or if an extension runs where the remote extension host runs. The extension kind * is defined in the `package.json`-file of extensions but can also be refined * via the `remote.extensionKind`-setting. When no remote extension host exists, - * the value is [`ExtensionKind.UI`](#ExtensionKind.UI). + * the value is {@link ExtensionKind.UI `ExtensionKind.UI`}. */ extensionKind: ExtensionKind; @@ -5966,13 +5993,13 @@ declare module 'vscode' { /** * A memento object that stores state in the context - * of the currently opened [workspace](#workspace.workspaceFolders). + * of the currently opened {@link workspace.workspaceFolders workspace}. */ readonly workspaceState: Memento; /** * A memento object that stores state independent - * of the current opened [workspace](#workspace.workspaceFolders). + * of the current opened {@link workspace.workspaceFolders workspace}. */ readonly globalState: Memento & { /** @@ -5988,11 +6015,12 @@ declare module 'vscode' { * * @param keys The set of keys whose values are synced. */ - setKeysForSync(keys: string[]): void; + setKeysForSync(keys: readonly string[]): void; }; /** - * A storage utility for secrets. + * A storage utility for secrets. Secrets are persisted across reloads and are independent of the + * current opened {@link workspace.workspaceFolders workspace}. */ readonly secrets: SecretStorage; @@ -6003,7 +6031,7 @@ declare module 'vscode' { /** * The absolute file path of the directory containing the extension. Shorthand - * notation for [ExtensionContext.extensionUri.fsPath](#TextDocument.uri) (independent of the uri scheme). + * notation for {@link TextDocument.uri ExtensionContext.extensionUri.fsPath} (independent of the uri scheme). */ readonly extensionPath: string; @@ -6016,8 +6044,8 @@ declare module 'vscode' { /** * Get the absolute path of a resource contained in the extension. * - * *Note* that an absolute uri can be constructed via [`Uri.joinPath`](#Uri.joinPath) and - * [`extensionUri`](#ExtensionContext.extensionUri), e.g. `vscode.Uri.joinPath(context.extensionUri, relativePath);` + * *Note* that an absolute uri can be constructed via {@link Uri.joinPath `Uri.joinPath`} and + * {@link ExtensionContext.extensionUri `extensionUri`}, e.g. `vscode.Uri.joinPath(context.extensionUri, relativePath);` * * @param relativePath A relative path to a resource contained in the extension. * @return The absolute path of the resource. @@ -6030,10 +6058,10 @@ declare module 'vscode' { * up to the extension. However, the parent directory is guaranteed to be existent. * The value is `undefined` when no workspace nor folder has been opened. * - * Use [`workspaceState`](#ExtensionContext.workspaceState) or - * [`globalState`](#ExtensionContext.globalState) to store key value data. + * Use {@link ExtensionContext.workspaceState `workspaceState`} or + * {@link ExtensionContext.globalState `globalState`} to store key value data. * - * @see [`workspace.fs`](#FileSystem) for how to read and write files and folders from + * @see {@link FileSystem `workspace.fs`} for how to read and write files and folders from * an uri. */ readonly storageUri: Uri | undefined; @@ -6043,10 +6071,10 @@ declare module 'vscode' { * can store private state. The directory might not exist on disk and creation is * up to the extension. However, the parent directory is guaranteed to be existent. * - * Use [`workspaceState`](#ExtensionContext.workspaceState) or - * [`globalState`](#ExtensionContext.globalState) to store key value data. + * Use {@link ExtensionContext.workspaceState `workspaceState`} or + * {@link ExtensionContext.globalState `globalState`} to store key value data. * - * @deprecated Use [storageUri](#ExtensionContext.storageUri) instead. + * @deprecated Use {@link ExtensionContext.storageUri storageUri} instead. */ readonly storagePath: string | undefined; @@ -6055,9 +6083,9 @@ declare module 'vscode' { * The directory might not exist on disk and creation is * up to the extension. However, the parent directory is guaranteed to be existent. * - * Use [`globalState`](#ExtensionContext.globalState) to store key value data. + * Use {@link ExtensionContext.globalState `globalState`} to store key value data. * - * @see [`workspace.fs`](#FileSystem) for how to read and write files and folders from + * @see {@link FileSystem `workspace.fs`} for how to read and write files and folders from * an uri. */ readonly globalStorageUri: Uri; @@ -6067,9 +6095,9 @@ declare module 'vscode' { * The directory might not exist on disk and creation is * up to the extension. However, the parent directory is guaranteed to be existent. * - * Use [`globalState`](#ExtensionContext.globalState) to store key value data. + * Use {@link ExtensionContext.globalState `globalState`} to store key value data. * - * @deprecated Use [globalStorageUri](#ExtensionContext.globalStorageUri) instead. + * @deprecated Use {@link ExtensionContext.globalStorageUri globalStorageUri} instead. */ readonly globalStoragePath: string; @@ -6078,7 +6106,7 @@ declare module 'vscode' { * The directory might not exist on disk and creation is up to the extension. However, * the parent directory is guaranteed to be existent. * - * @see [`workspace.fs`](#FileSystem) for how to read and write files and folders from + * @see {@link FileSystem `workspace.fs`} for how to read and write files and folders from * an uri. */ readonly logUri: Uri; @@ -6088,7 +6116,7 @@ declare module 'vscode' { * The directory might not exist on disk and creation is up to the extension. However, * the parent directory is guaranteed to be existent. * - * @deprecated Use [logUri](#ExtensionContext.logUri) instead. + * @deprecated Use {@link ExtensionContext.logUri logUri} instead. */ readonly logPath: string; @@ -6561,9 +6589,9 @@ declare module 'vscode' { /** * Constructs a CustomExecution task object. The callback will be executed when the task is run, at which point the * extension should return the Pseudoterminal it will "run in". The task should wait to do further execution until - * [Pseudoterminal.open](#Pseudoterminal.open) is called. Task cancellation should be handled using - * [Pseudoterminal.close](#Pseudoterminal.close). When the task is complete fire - * [Pseudoterminal.onDidClose](#Pseudoterminal.onDidClose). + * {@link Pseudoterminal.open} is called. Task cancellation should be handled using + * {@link Pseudoterminal.close}. When the task is complete fire + * {@link Pseudoterminal.onDidClose}. * @param callback The callback that will be called when the task is started by a user. Any ${} style variables that * were in the task definition will be resolved and passed into the callback as `resolvedDefinition`. */ @@ -6646,7 +6674,7 @@ declare module 'vscode' { /** * A human-readable string which is rendered less prominently on a separate line in places - * where the task's name is displayed. Supports rendering of [theme icons](#ThemeIcon) + * where the task's name is displayed. Supports rendering of {@link ThemeIcon theme icons} * via the `$()`-syntax. */ detail?: string; @@ -6663,7 +6691,7 @@ declare module 'vscode' { /** * A human-readable string describing the source of this shell task, e.g. 'gulp' - * or 'npm'. Supports rendering of [theme icons](#ThemeIcon) via the `$()`-syntax. + * or 'npm'. Supports rendering of {@link ThemeIcon theme icons} via the `$()`-syntax. */ source: string; @@ -6694,7 +6722,7 @@ declare module 'vscode' { /** * A task provider allows to add tasks to the task service. - * A task provider is registered via #tasks.registerTaskProvider. + * A task provider is registered via {@link tasks.registerTaskProvider}. */ export interface TaskProvider { /** @@ -6705,7 +6733,7 @@ declare module 'vscode' { provideTasks(token: CancellationToken): ProviderResult; /** - * Resolves a task that has no [`execution`](#Task.execution) set. Tasks are + * Resolves a task that has no {@link Task.execution `execution`} set. Tasks are * often created from information found in the `tasks.json`-file. Such tasks miss * the information on how to execute them and a task provider must fill in * the missing information in the `resolveTask`-method. This method will not be @@ -6823,7 +6851,7 @@ declare module 'vscode' { * * @param type The task kind type this provider is registered for. * @param provider A task provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerTaskProvider(type: string, provider: TaskProvider): Disposable; @@ -6851,7 +6879,7 @@ declare module 'vscode' { /** * The currently active task executions or an empty array. */ - export const taskExecutions: ReadonlyArray; + export const taskExecutions: readonly TaskExecution[]; /** * Fires when a task starts. @@ -6991,7 +7019,7 @@ declare module 'vscode' { /** * A code that identifies this error. * - * Possible values are names of errors, like [`FileNotFound`](#FileSystemError.FileNotFound), + * Possible values are names of errors, like {@link FileSystemError.FileNotFound `FileNotFound`}, * or `Unknown` for unspecified errors. */ readonly code: string; @@ -7039,22 +7067,22 @@ declare module 'vscode' { * and to manage files and folders. It allows extensions to serve files from remote places, * like ftp-servers, and to seamlessly integrate those into the editor. * - * * *Note 1:* The filesystem provider API works with [uris](#Uri) and assumes hierarchical + * * *Note 1:* The filesystem provider API works with {@link Uri uris} and assumes hierarchical * paths, e.g. `foo:/my/path` is a child of `foo:/my/` and a parent of `foo:/my/path/deeper`. * * *Note 2:* There is an activation event `onFileSystem:` that fires when a file * or folder is being accessed. - * * *Note 3:* The word 'file' is often used to denote all [kinds](#FileType) of files, e.g. + * * *Note 3:* The word 'file' is often used to denote all {@link FileType kinds} of files, e.g. * folders, symbolic links, and regular files. */ export interface FileSystemProvider { /** * An event to signal that a resource has been created, changed, or deleted. This - * event should fire for resources that are being [watched](#FileSystemProvider.watch) + * event should fire for resources that are being {@link FileSystemProvider.watch watched} * by clients of this provider. * * *Note:* It is important that the metadata of the file that changed provides an - * updated `mtime` that advanced from the previous value in the [stat](#FileStat) and a + * updated `mtime` that advanced from the previous value in the {@link FileStat stat} and a * correct `size` value. Otherwise there may be optimizations in place that will not show * the change in an editor for example. */ @@ -7077,21 +7105,21 @@ declare module 'vscode' { * Retrieve metadata about a file. * * Note that the metadata for symbolic links should be the metadata of the file they refer to. - * Still, the [SymbolicLink](#FileType.SymbolicLink)-type must be used in addition to the actual type, e.g. + * Still, the {@link FileType.SymbolicLink SymbolicLink}-type must be used in addition to the actual type, e.g. * `FileType.SymbolicLink | FileType.Directory`. * * @param uri The uri of the file to retrieve metadata about. * @return The file metadata about the file. - * @throws [`FileNotFound`](#FileSystemError.FileNotFound) when `uri` doesn't exist. + * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `uri` doesn't exist. */ stat(uri: Uri): FileStat | Thenable; /** - * Retrieve all entries of a [directory](#FileType.Directory). + * Retrieve all entries of a {@link FileType.Directory directory}. * * @param uri The uri of the folder. * @return An array of name/type-tuples or a thenable that resolves to such. - * @throws [`FileNotFound`](#FileSystemError.FileNotFound) when `uri` doesn't exist. + * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `uri` doesn't exist. */ readDirectory(uri: Uri): [string, FileType][] | Thenable<[string, FileType][]>; @@ -7099,9 +7127,9 @@ declare module 'vscode' { * Create a new directory (Note, that new files are created via `write`-calls). * * @param uri The uri of the new folder. - * @throws [`FileNotFound`](#FileSystemError.FileNotFound) when the parent of `uri` doesn't exist, e.g. no mkdirp-logic required. - * @throws [`FileExists`](#FileSystemError.FileExists) when `uri` already exists. - * @throws [`NoPermissions`](#FileSystemError.NoPermissions) when permissions aren't sufficient. + * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when the parent of `uri` doesn't exist, e.g. no mkdirp-logic required. + * @throws {@link FileSystemError.FileExists `FileExists`} when `uri` already exists. + * @throws {@link FileSystemError.NoPermissions `NoPermissions`} when permissions aren't sufficient. */ createDirectory(uri: Uri): void | Thenable; @@ -7110,7 +7138,7 @@ declare module 'vscode' { * * @param uri The uri of the file. * @return An array of bytes or a thenable that resolves to such. - * @throws [`FileNotFound`](#FileSystemError.FileNotFound) when `uri` doesn't exist. + * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `uri` doesn't exist. */ readFile(uri: Uri): Uint8Array | Thenable; @@ -7120,10 +7148,10 @@ declare module 'vscode' { * @param uri The uri of the file. * @param content The new content of the file. * @param options Defines if missing files should or must be created. - * @throws [`FileNotFound`](#FileSystemError.FileNotFound) when `uri` doesn't exist and `create` is not set. - * @throws [`FileNotFound`](#FileSystemError.FileNotFound) when the parent of `uri` doesn't exist and `create` is set, e.g. no mkdirp-logic required. - * @throws [`FileExists`](#FileSystemError.FileExists) when `uri` already exists, `create` is set but `overwrite` is not set. - * @throws [`NoPermissions`](#FileSystemError.NoPermissions) when permissions aren't sufficient. + * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `uri` doesn't exist and `create` is not set. + * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when the parent of `uri` doesn't exist and `create` is set, e.g. no mkdirp-logic required. + * @throws {@link FileSystemError.FileExists `FileExists`} when `uri` already exists, `create` is set but `overwrite` is not set. + * @throws {@link FileSystemError.NoPermissions `NoPermissions`} when permissions aren't sufficient. */ writeFile(uri: Uri, content: Uint8Array, options: { create: boolean, overwrite: boolean }): void | Thenable; @@ -7132,8 +7160,8 @@ declare module 'vscode' { * * @param uri The resource that is to be deleted. * @param options Defines if deletion of folders is recursive. - * @throws [`FileNotFound`](#FileSystemError.FileNotFound) when `uri` doesn't exist. - * @throws [`NoPermissions`](#FileSystemError.NoPermissions) when permissions aren't sufficient. + * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `uri` doesn't exist. + * @throws {@link FileSystemError.NoPermissions `NoPermissions`} when permissions aren't sufficient. */ delete(uri: Uri, options: { recursive: boolean }): void | Thenable; @@ -7143,10 +7171,10 @@ declare module 'vscode' { * @param oldUri The existing file. * @param newUri The new location. * @param options Defines if existing files should be overwritten. - * @throws [`FileNotFound`](#FileSystemError.FileNotFound) when `oldUri` doesn't exist. - * @throws [`FileNotFound`](#FileSystemError.FileNotFound) when parent of `newUri` doesn't exist, e.g. no mkdirp-logic required. - * @throws [`FileExists`](#FileSystemError.FileExists) when `newUri` exists and when the `overwrite` option is not `true`. - * @throws [`NoPermissions`](#FileSystemError.NoPermissions) when permissions aren't sufficient. + * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `oldUri` doesn't exist. + * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when parent of `newUri` doesn't exist, e.g. no mkdirp-logic required. + * @throws {@link FileSystemError.FileExists `FileExists`} when `newUri` exists and when the `overwrite` option is not `true`. + * @throws {@link FileSystemError.NoPermissions `NoPermissions`} when permissions aren't sufficient. */ rename(oldUri: Uri, newUri: Uri, options: { overwrite: boolean }): void | Thenable; @@ -7157,21 +7185,21 @@ declare module 'vscode' { * @param source The existing file. * @param destination The destination location. * @param options Defines if existing files should be overwritten. - * @throws [`FileNotFound`](#FileSystemError.FileNotFound) when `source` doesn't exist. - * @throws [`FileNotFound`](#FileSystemError.FileNotFound) when parent of `destination` doesn't exist, e.g. no mkdirp-logic required. - * @throws [`FileExists`](#FileSystemError.FileExists) when `destination` exists and when the `overwrite` option is not `true`. - * @throws [`NoPermissions`](#FileSystemError.NoPermissions) when permissions aren't sufficient. + * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when `source` doesn't exist. + * @throws {@link FileSystemError.FileNotFound `FileNotFound`} when parent of `destination` doesn't exist, e.g. no mkdirp-logic required. + * @throws {@link FileSystemError.FileExists `FileExists`} when `destination` exists and when the `overwrite` option is not `true`. + * @throws {@link FileSystemError.NoPermissions `NoPermissions`} when permissions aren't sufficient. */ copy?(source: Uri, destination: Uri, options: { overwrite: boolean }): void | Thenable; } /** * The file system interface exposes the editor's built-in and contributed - * [file system providers](#FileSystemProvider). It allows extensions to work + * {@link FileSystemProvider file system providers}. It allows extensions to work * with files from the local disk as well as files from remote places, like the * remote extension host or ftp-servers. * - * *Note* that an instance of this interface is available as [`workspace.fs`](#workspace.fs). + * *Note* that an instance of this interface is available as {@link workspace.fs `workspace.fs`}. */ export interface FileSystem { @@ -7184,7 +7212,7 @@ declare module 'vscode' { stat(uri: Uri): Thenable; /** - * Retrieve all entries of a [directory](#FileType.Directory). + * Retrieve all entries of a {@link FileType.Directory directory}. * * @param uri The uri of the folder. * @return An array of name/type-tuples or a thenable that resolves to such. @@ -7299,7 +7327,7 @@ declare module 'vscode' { * * Pass in an empty array to disallow access to any local resources. */ - readonly localResourceRoots?: ReadonlyArray; + readonly localResourceRoots?: readonly Uri[]; /** * Mappings of localhost ports used inside the webview. @@ -7314,7 +7342,7 @@ declare module 'vscode' { * *Note* that port mappings only work for `http` or `https` urls. Websocket urls (e.g. `ws://localhost:3000`) * cannot be mapped to another port. */ - readonly portMapping?: ReadonlyArray; + readonly portMapping?: readonly WebviewPortMapping[]; } /** @@ -7332,7 +7360,7 @@ declare module 'vscode' { * This should be a complete, valid html document. Changing this property causes the webview to be reloaded. * * Webviews are sandboxed from normal extension process, so all communication with the webview must use - * message passing. To send a message from the extension to the webview, use [`postMessage`](#Webview.postMessage). + * message passing. To send a message from the extension to the webview, use {@link Webview.postMessage `postMessage`}. * To send message from the webview back to an extension, use the `acquireVsCodeApi` function inside the webview * to get a handle to VS Code's api and then call `.postMessage()`: * @@ -7343,8 +7371,8 @@ declare module 'vscode' { * * ``` * - * To load a resources from the workspace inside a webview, use the `[asWebviewUri](#Webview.asWebviewUri)` method - * and ensure the resource's directory is listed in [`WebviewOptions.localResourceRoots`](#WebviewOptions.localResourceRoots). + * To load a resources from the workspace inside a webview, use the `{@link Webview.asWebviewUri asWebviewUri}` method + * and ensure the resource's directory is listed in {@link WebviewOptions.localResourceRoots `WebviewOptions.localResourceRoots`}. * * Keep in mind that even though webviews are sandboxed, they still allow running scripts and loading arbitrary content, * so extensions must follow all standard web security best practices when working with webviews. This includes @@ -7369,6 +7397,16 @@ declare module 'vscode' { * background with `retainContextWhenHidden`). * * @param message Body of the message. This must be a string or other json serializable object. + * + * For older versions of vscode, if an `ArrayBuffer` is included in `message`, + * it will not be serialized properly and will not be received by the webview. + * Similarly any TypedArrays, such as a `Uint8Array`, will be very inefficiently + * serialized and will also not be recreated as a typed array inside the webview. + * + * However if your extension targets vscode 1.57+ in the `engines` field of its + * `package.json`, any `ArrayBuffer` values that appear in `message` will be more + * efficiently transferred to the webview and will also be correctly recreated inside + * of the webview. */ postMessage(message: any): Thenable; @@ -7447,7 +7485,7 @@ declare module 'vscode' { iconPath?: Uri | { light: Uri; dark: Uri }; /** - * [`Webview`](#Webview) belonging to the panel. + * {@link Webview `Webview`} belonging to the panel. */ readonly webview: Webview; @@ -7692,7 +7730,7 @@ declare module 'vscode' { /** * Provider for text based custom editors. * - * Text based custom editors use a [`TextDocument`](#TextDocument) as their data model. This considerably simplifies + * Text based custom editors use a {@link TextDocument `TextDocument`} as their data model. This considerably simplifies * implementing a custom editor as it allows VS Code to handle many common operations such as * undo and backup. The provider is responsible for synchronizing text changes between the webview and the `TextDocument`. */ @@ -7711,7 +7749,7 @@ declare module 'vscode' { * * During resolve, the provider must fill in the initial html for the content webview panel and hook up all * the event listeners on it that it is interested in. The provider can also hold onto the `WebviewPanel` to - * use later for example in a command. See [`WebviewPanel`](#WebviewPanel) for additional details. + * use later for example in a command. See {@link WebviewPanel `WebviewPanel`} for additional details. * * @param token A cancellation token that indicates the result is no longer needed. * @@ -7721,7 +7759,7 @@ declare module 'vscode' { } /** - * Represents a custom document used by a [`CustomEditorProvider`](#CustomEditorProvider). + * Represents a custom document used by a {@link CustomEditorProvider `CustomEditorProvider`}. * * Custom documents are only used within a given `CustomEditorProvider`. The lifecycle of a `CustomDocument` is * managed by VS Code. When no more references remain to a `CustomDocument`, it is disposed of. @@ -7742,9 +7780,9 @@ declare module 'vscode' { } /** - * Event triggered by extensions to signal to VS Code that an edit has occurred on an [`CustomDocument`](#CustomDocument). + * Event triggered by extensions to signal to VS Code that an edit has occurred on an {@link CustomDocument `CustomDocument`}. * - * @see [`CustomDocumentProvider.onDidChangeCustomDocument`](#CustomDocumentProvider.onDidChangeCustomDocument). + * @see {@link CustomEditorProvider.onDidChangeCustomDocument `CustomEditorProvider.onDidChangeCustomDocument`}. */ interface CustomDocumentEditEvent { @@ -7780,10 +7818,10 @@ declare module 'vscode' { } /** - * Event triggered by extensions to signal to VS Code that the content of a [`CustomDocument`](#CustomDocument) + * Event triggered by extensions to signal to VS Code that the content of a {@link CustomDocument `CustomDocument`} * has changed. * - * @see [`CustomDocumentProvider.onDidChangeCustomDocument`](#CustomDocumentProvider.onDidChangeCustomDocument). + * @see {@link CustomEditorProvider.onDidChangeCustomDocument `CustomEditorProvider.onDidChangeCustomDocument`}. */ interface CustomDocumentContentChangeEvent { /** @@ -7793,7 +7831,7 @@ declare module 'vscode' { } /** - * A backup for an [`CustomDocument`](#CustomDocument). + * A backup for an {@link CustomDocument `CustomDocument`}. */ interface CustomDocumentBackup { /** @@ -7813,7 +7851,7 @@ declare module 'vscode' { } /** - * Additional information used to implement [`CustomEditableDocument.backup`](#CustomEditableDocument.backup). + * Additional information used to implement {@link CustomEditableDocument.backup `CustomEditableDocument.backup`}. */ interface CustomDocumentBackupContext { /** @@ -7851,10 +7889,10 @@ declare module 'vscode' { /** * Provider for readonly custom editors that use a custom document model. * - * Custom editors use [`CustomDocument`](#CustomDocument) as their document model instead of a [`TextDocument`](#TextDocument). + * Custom editors use {@link CustomDocument `CustomDocument`} as their document model instead of a {@link TextDocument `TextDocument`}. * * You should use this type of custom editor when dealing with binary files or more complex scenarios. For simple - * text based documents, use [`CustomTextEditorProvider`](#CustomTextEditorProvider) instead. + * text based documents, use {@link CustomTextEditorProvider `CustomTextEditorProvider`} instead. * * @param T Type of the custom document returned by this provider. */ @@ -7889,7 +7927,7 @@ declare module 'vscode' { * * During resolve, the provider must fill in the initial html for the content webview panel and hook up all * the event listeners on it that it is interested in. The provider can also hold onto the `WebviewPanel` to - * use later for example in a command. See [`WebviewPanel`](#WebviewPanel) for additional details. + * use later for example in a command. See {@link WebviewPanel `WebviewPanel`} for additional details. * * @param token A cancellation token that indicates the result is no longer needed. * @@ -7901,11 +7939,11 @@ declare module 'vscode' { /** * Provider for editable custom editors that use a custom document model. * - * Custom editors use [`CustomDocument`](#CustomDocument) as their document model instead of a [`TextDocument`](#TextDocument). + * Custom editors use {@link CustomDocument `CustomDocument`} as their document model instead of a {@link TextDocument `TextDocument`}. * This gives extensions full control over actions such as edit, save, and backup. * * You should use this type of custom editor when dealing with binary files or more complex scenarios. For simple - * text based documents, use [`CustomTextEditorProvider`](#CustomTextEditorProvider) instead. + * text based documents, use {@link CustomTextEditorProvider `CustomTextEditorProvider`} instead. * * @param T Type of the custom document returned by this provider. */ @@ -8097,7 +8135,7 @@ declare module 'vscode' { export const isTelemetryEnabled: boolean; /** - * An [event](#Event) which fires when the user enabled or disables telemetry. + * An {@link Event} which fires when the user enabled or disables telemetry. * `true` if the user has enabled telemetry or `false` if the user has disabled telemetry. */ export const onDidChangeTelemetryEnabled: Event; @@ -8108,7 +8146,7 @@ declare module 'vscode' { * * *Note* that the value is `undefined` when there is no remote extension host but that the * value is defined in all extension hosts (local and remote) in case a remote extension host - * exists. Use [`Extension#extensionKind`](#Extension.extensionKind) to know if + * exists. Use {@link Extension.extensionKind} to know if * a specific extension runs remote or not. */ export const remoteName: string | undefined; @@ -8134,7 +8172,7 @@ declare module 'vscode' { * * a mail client (`mailto:`) * * VSCode itself (`vscode:` from `vscode.env.uriScheme`) * - * *Note* that [`showTextDocument`](#window.showTextDocument) is the right + * *Note* that {@link window.showTextDocument `showTextDocument`} is the right * way to open a text document inside the editor, not this function. * * @param target The uri that should be opened. @@ -8161,7 +8199,7 @@ declare module 'vscode' { * * #### `vscode.env.uriScheme` * - * Creates a uri that - if opened in a browser (e.g. via `openExternal`) - will result in a registered [UriHandler](#UriHandler) + * Creates a uri that - if opened in a browser (e.g. via `openExternal`) - will result in a registered {@link UriHandler} * to trigger. * * Extensions should not make any assumptions about the resulting uri and should not alter it in anyway. @@ -8169,7 +8207,7 @@ declare module 'vscode' { * argument to the server to authenticate to. * * *Note* that if the server decides to add additional query parameters to the uri (e.g. a token or secret), it - * will appear in the uri that is passed to the [UriHandler](#UriHandler). + * will appear in the uri that is passed to the {@link UriHandler}. * * **Example** of an authentication flow: * ```typescript @@ -8198,9 +8236,9 @@ declare module 'vscode' { * Namespace for dealing with commands. In short, a command is a function with a * unique identifier. The function is sometimes also called _command handler_. * - * Commands can be added to the editor using the [registerCommand](#commands.registerCommand) - * and [registerTextEditorCommand](#commands.registerTextEditorCommand) functions. Commands - * can be executed [manually](#commands.executeCommand) or from a UI gesture. Those are: + * Commands can be added to the editor using the {@link commands.registerCommand registerCommand} + * and {@link commands.registerTextEditorCommand registerTextEditorCommand} functions. Commands + * can be executed {@link commands.executeCommand manually} or from a UI gesture. Those are: * * * palette - Use the `commands`-section in `package.json` to make a command show in * the [command palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette). @@ -8250,14 +8288,14 @@ declare module 'vscode' { * Registers a text editor command that can be invoked via a keyboard shortcut, * a menu item, an action, or directly. * - * Text editor commands are different from ordinary [commands](#commands.registerCommand) as + * Text editor commands are different from ordinary {@link commands.registerCommand commands} as * they only execute when there is an active editor when the command is called. Also, the * command handler of an editor command has access to the active editor and to an - * [edit](#TextEditorEdit)-builder. Note that the edit-builder is only valid while the + * {@link TextEditorEdit edit}-builder. Note that the edit-builder is only valid while the * callback executes. * * @param command A unique identifier for the command. - * @param callback A command handler function with access to an [editor](#TextEditor) and an [edit](#TextEditorEdit). + * @param callback A command handler function with access to an {@link TextEditor editor} and an {@link TextEditorEdit edit}. * @param thisArg The `this` context used when invoking the handler function. * @return Disposable which unregisters this command on disposal. */ @@ -8268,7 +8306,7 @@ declare module 'vscode' { * * * *Note 1:* When executing an editor command not all types are allowed to * be passed as arguments. Allowed are the primitive types `string`, `boolean`, - * `number`, `undefined`, and `null`, as well as [`Position`](#Position), [`Range`](#Range), [`Uri`](#Uri) and [`Location`](#Location). + * `number`, `undefined`, and `null`, as well as {@link Position `Position`}, {@link Range `Range`}, {@link Uri `Uri`} and {@link Location `Location`}. * * *Note 2:* There are no restrictions when executing commands that have been contributed * by extensions. * @@ -8301,16 +8339,16 @@ declare module 'vscode' { } /** - * A uri handler is responsible for handling system-wide [uris](#Uri). + * A uri handler is responsible for handling system-wide {@link Uri uris}. * - * @see [window.registerUriHandler](#window.registerUriHandler). + * @see {@link window.registerUriHandler}. */ export interface UriHandler { /** - * Handle the provided system-wide [uri](#Uri). + * Handle the provided system-wide {@link Uri}. * - * @see [window.registerUriHandler](#window.registerUriHandler). + * @see {@link window.registerUriHandler}. */ handleUri(uri: Uri): ProviderResult; } @@ -8335,42 +8373,42 @@ declare module 'vscode' { export let visibleTextEditors: TextEditor[]; /** - * An [event](#Event) which fires when the [active editor](#window.activeTextEditor) + * An {@link Event} which fires when the {@link window.activeTextEditor active editor} * has changed. *Note* that the event also fires when the active editor changes * to `undefined`. */ export const onDidChangeActiveTextEditor: Event; /** - * An [event](#Event) which fires when the array of [visible editors](#window.visibleTextEditors) + * An {@link Event} which fires when the array of {@link window.visibleTextEditors visible editors} * has changed. */ export const onDidChangeVisibleTextEditors: Event; /** - * An [event](#Event) which fires when the selection in an editor has changed. + * An {@link Event} which fires when the selection in an editor has changed. */ export const onDidChangeTextEditorSelection: Event; /** - * An [event](#Event) which fires when the visible ranges of an editor has changed. + * An {@link Event} which fires when the visible ranges of an editor has changed. */ export const onDidChangeTextEditorVisibleRanges: Event; /** - * An [event](#Event) which fires when the options of an editor have changed. + * An {@link Event} which fires when the options of an editor have changed. */ export const onDidChangeTextEditorOptions: Event; /** - * An [event](#Event) which fires when the view column of an editor has changed. + * An {@link Event} which fires when the view column of an editor has changed. */ export const onDidChangeTextEditorViewColumn: Event; /** * The currently opened terminals or an empty array. */ - export const terminals: ReadonlyArray; + export const terminals: readonly Terminal[]; /** * The currently active terminal or `undefined`. The active terminal is the one that @@ -8379,20 +8417,20 @@ declare module 'vscode' { export const activeTerminal: Terminal | undefined; /** - * An [event](#Event) which fires when the [active terminal](#window.activeTerminal) + * An {@link Event} which fires when the {@link window.activeTerminal active terminal} * has changed. *Note* that the event also fires when the active terminal changes * to `undefined`. */ export const onDidChangeActiveTerminal: Event; /** - * An [event](#Event) which fires when a terminal has been created, either through the - * [createTerminal](#window.createTerminal) API or commands. + * An {@link Event} which fires when a terminal has been created, either through the + * {@link window.createTerminal createTerminal} API or commands. */ export const onDidOpenTerminal: Event; /** - * An [event](#Event) which fires when a terminal is disposed. + * An {@link Event} which fires when a terminal is disposed. */ export const onDidCloseTerminal: Event; @@ -8402,42 +8440,42 @@ declare module 'vscode' { export const state: WindowState; /** - * An [event](#Event) which fires when the focus state of the current window + * An {@link Event} which fires when the focus state of the current window * changes. The value of the event represents whether the window is focused. */ export const onDidChangeWindowState: Event; /** - * Show the given document in a text editor. A [column](#ViewColumn) can be provided - * to control where the editor is being shown. Might change the [active editor](#window.activeTextEditor). + * Show the given document in a text editor. A {@link ViewColumn column} can be provided + * to control where the editor is being shown. Might change the {@link window.activeTextEditor active editor}. * * @param document A text document to be shown. - * @param column A view column in which the [editor](#TextEditor) should be shown. The default is the [active](#ViewColumn.Active), other values - * are adjusted to be `Min(column, columnCount + 1)`, the [active](#ViewColumn.Active)-column is not adjusted. Use [`ViewColumn.Beside`](#ViewColumn.Beside) + * @param column A view column in which the {@link TextEditor editor} should be shown. The default is the {@link ViewColumn.Active active}, other values + * are adjusted to be `Min(column, columnCount + 1)`, the {@link ViewColumn.Active active}-column is not adjusted. Use {@link ViewColumn.Beside `ViewColumn.Beside`} * to open the editor to the side of the currently active one. * @param preserveFocus When `true` the editor will not take focus. - * @return A promise that resolves to an [editor](#TextEditor). + * @return A promise that resolves to an {@link TextEditor editor}. */ export function showTextDocument(document: TextDocument, column?: ViewColumn, preserveFocus?: boolean): Thenable; /** - * Show the given document in a text editor. [Options](#TextDocumentShowOptions) can be provided - * to control options of the editor is being shown. Might change the [active editor](#window.activeTextEditor). + * Show the given document in a text editor. {@link TextDocumentShowOptions Options} can be provided + * to control options of the editor is being shown. Might change the {@link window.activeTextEditor active editor}. * * @param document A text document to be shown. - * @param options [Editor options](#TextDocumentShowOptions) to configure the behavior of showing the [editor](#TextEditor). - * @return A promise that resolves to an [editor](#TextEditor). + * @param options {@link TextDocumentShowOptions Editor options} to configure the behavior of showing the {@link TextEditor editor}. + * @return A promise that resolves to an {@link TextEditor editor}. */ export function showTextDocument(document: TextDocument, options?: TextDocumentShowOptions): Thenable; /** * A short-hand for `openTextDocument(uri).then(document => showTextDocument(document, options))`. * - * @see [openTextDocument](#openTextDocument) + * @see {@link openTextDocument} * * @param uri A resource identifier. - * @param options [Editor options](#TextDocumentShowOptions) to configure the behavior of showing the [editor](#TextEditor). - * @return A promise that resolves to an [editor](#TextEditor). + * @param options {@link TextDocumentShowOptions Editor options} to configure the behavior of showing the {@link TextEditor editor}. + * @return A promise that resolves to an {@link TextEditor editor}. */ export function showTextDocument(uri: Uri, options?: TextDocumentShowOptions): Thenable; @@ -8473,7 +8511,7 @@ declare module 'vscode' { /** * Show an information message. * - * @see [showInformationMessage](#window.showInformationMessage) + * @see {@link window.showInformationMessage showInformationMessage} * * @param message The message to show. * @param items A set of items that will be rendered as actions in the message. @@ -8484,7 +8522,7 @@ declare module 'vscode' { /** * Show an information message. * - * @see [showInformationMessage](#window.showInformationMessage) + * @see {@link window.showInformationMessage showInformationMessage} * * @param message The message to show. * @param options Configures the behaviour of the message. @@ -8496,7 +8534,7 @@ declare module 'vscode' { /** * Show a warning message. * - * @see [showInformationMessage](#window.showInformationMessage) + * @see {@link window.showInformationMessage showInformationMessage} * * @param message The message to show. * @param items A set of items that will be rendered as actions in the message. @@ -8507,7 +8545,7 @@ declare module 'vscode' { /** * Show a warning message. * - * @see [showInformationMessage](#window.showInformationMessage) + * @see {@link window.showInformationMessage showInformationMessage} * * @param message The message to show. * @param options Configures the behaviour of the message. @@ -8519,7 +8557,7 @@ declare module 'vscode' { /** * Show a warning message. * - * @see [showInformationMessage](#window.showInformationMessage) + * @see {@link window.showInformationMessage showInformationMessage} * * @param message The message to show. * @param items A set of items that will be rendered as actions in the message. @@ -8530,7 +8568,7 @@ declare module 'vscode' { /** * Show a warning message. * - * @see [showInformationMessage](#window.showInformationMessage) + * @see {@link window.showInformationMessage showInformationMessage} * * @param message The message to show. * @param options Configures the behaviour of the message. @@ -8542,7 +8580,7 @@ declare module 'vscode' { /** * Show an error message. * - * @see [showInformationMessage](#window.showInformationMessage) + * @see {@link window.showInformationMessage showInformationMessage} * * @param message The message to show. * @param items A set of items that will be rendered as actions in the message. @@ -8553,7 +8591,7 @@ declare module 'vscode' { /** * Show an error message. * - * @see [showInformationMessage](#window.showInformationMessage) + * @see {@link window.showInformationMessage showInformationMessage} * * @param message The message to show. * @param options Configures the behaviour of the message. @@ -8565,7 +8603,7 @@ declare module 'vscode' { /** * Show an error message. * - * @see [showInformationMessage](#window.showInformationMessage) + * @see {@link window.showInformationMessage showInformationMessage} * * @param message The message to show. * @param items A set of items that will be rendered as actions in the message. @@ -8576,7 +8614,7 @@ declare module 'vscode' { /** * Show an error message. * - * @see [showInformationMessage](#window.showInformationMessage) + * @see {@link window.showInformationMessage showInformationMessage} * * @param message The message to show. * @param options Configures the behaviour of the message. @@ -8593,7 +8631,7 @@ declare module 'vscode' { * @param token A token that can be used to signal cancellation. * @return A promise that resolves to the selected items or `undefined`. */ - export function showQuickPick(items: string[] | Thenable, options: QuickPickOptions & { canPickMany: true; }, token?: CancellationToken): Thenable; + export function showQuickPick(items: readonly string[] | Thenable, options: QuickPickOptions & { canPickMany: true; }, token?: CancellationToken): Thenable; /** * Shows a selection list. @@ -8603,7 +8641,7 @@ declare module 'vscode' { * @param token A token that can be used to signal cancellation. * @return A promise that resolves to the selection or `undefined`. */ - export function showQuickPick(items: string[] | Thenable, options?: QuickPickOptions, token?: CancellationToken): Thenable; + export function showQuickPick(items: readonly string[] | Thenable, options?: QuickPickOptions, token?: CancellationToken): Thenable; /** * Shows a selection list allowing multiple selections. @@ -8613,7 +8651,7 @@ declare module 'vscode' { * @param token A token that can be used to signal cancellation. * @return A promise that resolves to the selected items or `undefined`. */ - export function showQuickPick(items: T[] | Thenable, options: QuickPickOptions & { canPickMany: true; }, token?: CancellationToken): Thenable; + export function showQuickPick(items: readonly T[] | Thenable, options: QuickPickOptions & { canPickMany: true; }, token?: CancellationToken): Thenable; /** * Shows a selection list. @@ -8623,10 +8661,10 @@ declare module 'vscode' { * @param token A token that can be used to signal cancellation. * @return A promise that resolves to the selected item or `undefined`. */ - export function showQuickPick(items: T[] | Thenable, options?: QuickPickOptions, token?: CancellationToken): Thenable; + export function showQuickPick(items: readonly T[] | Thenable, options?: QuickPickOptions, token?: CancellationToken): Thenable; /** - * Shows a selection list of [workspace folders](#workspace.workspaceFolders) to pick from. + * Shows a selection list of {@link workspace.workspaceFolders workspace folders} to pick from. * Returns `undefined` if no folder is open. * * @param options Configures the behavior of the workspace folder list. @@ -8666,30 +8704,30 @@ declare module 'vscode' { export function showInputBox(options?: InputBoxOptions, token?: CancellationToken): Thenable; /** - * Creates a [QuickPick](#QuickPick) to let the user pick an item from a list + * Creates a {@link QuickPick} to let the user pick an item from a list * of items of type T. * - * Note that in many cases the more convenient [window.showQuickPick](#window.showQuickPick) - * is easier to use. [window.createQuickPick](#window.createQuickPick) should be used - * when [window.showQuickPick](#window.showQuickPick) does not offer the required flexibility. + * Note that in many cases the more convenient {@link window.showQuickPick} + * is easier to use. {@link window.createQuickPick} should be used + * when {@link window.showQuickPick} does not offer the required flexibility. * - * @return A new [QuickPick](#QuickPick). + * @return A new {@link QuickPick}. */ export function createQuickPick(): QuickPick; /** - * Creates a [InputBox](#InputBox) to let the user enter some text input. + * Creates a {@link InputBox} to let the user enter some text input. * - * Note that in many cases the more convenient [window.showInputBox](#window.showInputBox) - * is easier to use. [window.createInputBox](#window.createInputBox) should be used - * when [window.showInputBox](#window.showInputBox) does not offer the required flexibility. + * Note that in many cases the more convenient {@link window.showInputBox} + * is easier to use. {@link window.createInputBox} should be used + * when {@link window.showInputBox} does not offer the required flexibility. * - * @return A new [InputBox](#InputBox). + * @return A new {@link InputBox}. */ export function createInputBox(): InputBox; /** - * Creates a new [output channel](#OutputChannel) with the given name. + * Creates a new {@link OutputChannel output channel} with the given name. * * @param name Human-readable string which will be used to represent the channel in the UI. */ @@ -8709,9 +8747,9 @@ declare module 'vscode' { /** * Set a message to the status bar. This is a short hand for the more powerful - * status bar [items](#window.createStatusBarItem). + * status bar {@link window.createStatusBarItem items}. * - * @param text The message to show, supports icon substitution as in status bar [items](#StatusBarItem.text). + * @param text The message to show, supports icon substitution as in status bar {@link StatusBarItem.text items}. * @param hideAfterTimeout Timeout in milliseconds after which the message will be disposed. * @return A disposable which hides the status bar message. */ @@ -8719,9 +8757,9 @@ declare module 'vscode' { /** * Set a message to the status bar. This is a short hand for the more powerful - * status bar [items](#window.createStatusBarItem). + * status bar {@link window.createStatusBarItem items}. * - * @param text The message to show, supports icon substitution as in status bar [items](#StatusBarItem.text). + * @param text The message to show, supports icon substitution as in status bar {@link StatusBarItem.text items}. * @param hideWhenDone Thenable on which completion (resolve or reject) the message will be disposed. * @return A disposable which hides the status bar message. */ @@ -8729,12 +8767,12 @@ declare module 'vscode' { /** * Set a message to the status bar. This is a short hand for the more powerful - * status bar [items](#window.createStatusBarItem). + * status bar {@link window.createStatusBarItem items}. * * *Note* that status bar messages stack and that they must be disposed when no * longer used. * - * @param text The message to show, supports icon substitution as in status bar [items](#StatusBarItem.text). + * @param text The message to show, supports icon substitution as in status bar {@link StatusBarItem.text items}. * @return A disposable which hides the status bar message. */ export function setStatusBarMessage(text: string): Disposable; @@ -8746,7 +8784,7 @@ declare module 'vscode' { * @deprecated Use `withProgress` instead. * * @param task A callback returning a promise. Progress increments can be reported with - * the provided [progress](#Progress)-object. + * the provided {@link Progress}-object. * @return The thenable the task did return. */ export function withScmProgress(task: (progress: Progress) => Thenable): Thenable; @@ -8754,17 +8792,17 @@ declare module 'vscode' { /** * Show progress in the editor. Progress is shown while running the given callback * and while the promise it returned isn't resolved nor rejected. The location at which - * progress should show (and other details) is defined via the passed [`ProgressOptions`](#ProgressOptions). + * progress should show (and other details) is defined via the passed {@link ProgressOptions `ProgressOptions`}. * * @param task A callback returning a promise. Progress state can be reported with - * the provided [progress](#Progress)-object. + * the provided {@link Progress}-object. * * To report discrete progress, use `increment` to indicate how much work has been completed. Each call with * a `increment` value will be summed up and reflected as overall progress until 100% is reached (a value of * e.g. `10` accounts for `10%` of work done). * Note that currently only `ProgressLocation.Notification` is capable of showing discrete progress. * - * To monitor if the operation has been cancelled by the user, use the provided [`CancellationToken`](#CancellationToken). + * To monitor if the operation has been cancelled by the user, use the provided {@link CancellationToken `CancellationToken`}. * Note that currently only `ProgressLocation.Notification` is supporting to show a cancel button to cancel the * long running operation. * @@ -8773,7 +8811,7 @@ declare module 'vscode' { export function withProgress(options: ProgressOptions, task: (progress: Progress<{ message?: string; increment?: number }>, token: CancellationToken) => Thenable): Thenable; /** - * Creates a status bar [item](#StatusBarItem). + * Creates a status bar {@link StatusBarItem item}. * * @param alignment The alignment of the item. * @param priority The priority of the item. Higher values mean the item should be shown more to the left. @@ -8782,7 +8820,17 @@ declare module 'vscode' { export function createStatusBarItem(alignment?: StatusBarAlignment, priority?: number): StatusBarItem; /** - * Creates a [Terminal](#Terminal) with a backing shell process. The cwd of the terminal will be the workspace + * Creates a status bar {@link StatusBarItem item}. + * + * @param id The unique identifier of the item. + * @param alignment The alignment of the item. + * @param priority The priority of the item. Higher values mean the item should be shown more to the left. + * @return A new status bar item. + */ + export function createStatusBarItem(id: string, alignment?: StatusBarAlignment, priority?: number): StatusBarItem; + + /** + * Creates a {@link Terminal} with a backing shell process. The cwd of the terminal will be the workspace * directory if it exists. * * @param name Optional human-readable string which will be used to represent the terminal in the UI. @@ -8796,7 +8844,7 @@ declare module 'vscode' { export function createTerminal(name?: string, shellPath?: string, shellArgs?: string[] | string): Terminal; /** - * Creates a [Terminal](#Terminal) with a backing shell process. + * Creates a {@link Terminal} with a backing shell process. * * @param options A TerminalOptions object describing the characteristics of the new terminal. * @return A new Terminal. @@ -8805,35 +8853,35 @@ declare module 'vscode' { export function createTerminal(options: TerminalOptions): Terminal; /** - * Creates a [Terminal](#Terminal) where an extension controls its input and output. + * Creates a {@link Terminal} where an extension controls its input and output. * - * @param options An [ExtensionTerminalOptions](#ExtensionTerminalOptions) object describing + * @param options An {@link ExtensionTerminalOptions} object describing * the characteristics of the new terminal. * @return A new Terminal. */ export function createTerminal(options: ExtensionTerminalOptions): Terminal; /** - * Register a [TreeDataProvider](#TreeDataProvider) for the view contributed using the extension point `views`. - * This will allow you to contribute data to the [TreeView](#TreeView) and update if the data changes. + * Register a {@link TreeDataProvider} for the view contributed using the extension point `views`. + * This will allow you to contribute data to the {@link TreeView} and update if the data changes. * - * **Note:** To get access to the [TreeView](#TreeView) and perform operations on it, use [createTreeView](#window.createTreeView). + * **Note:** To get access to the {@link TreeView} and perform operations on it, use {@link window.createTreeView createTreeView}. * * @param viewId Id of the view contributed using the extension point `views`. - * @param treeDataProvider A [TreeDataProvider](#TreeDataProvider) that provides tree data for the view + * @param treeDataProvider A {@link TreeDataProvider} that provides tree data for the view */ export function registerTreeDataProvider(viewId: string, treeDataProvider: TreeDataProvider): Disposable; /** - * Create a [TreeView](#TreeView) for the view contributed using the extension point `views`. + * Create a {@link TreeView} for the view contributed using the extension point `views`. * @param viewId Id of the view contributed using the extension point `views`. - * @param options Options for creating the [TreeView](#TreeView) - * @returns a [TreeView](#TreeView). + * @param options Options for creating the {@link TreeView} + * @returns a {@link TreeView}. */ export function createTreeView(viewId: string, options: TreeViewOptions): TreeView; /** - * Registers a [uri handler](#UriHandler) capable of handling system-wide [uris](#Uri). + * Registers a {@link UriHandler uri handler} capable of handling system-wide {@link Uri uris}. * In case there are multiple windows open, the topmost window will handle the uri. * A uri handler is scoped to the extension it is contributed from; it will only * be able to handle uris which are directed to the extension itself. A uri must respect @@ -8859,7 +8907,7 @@ declare module 'vscode' { * Registers a webview panel serializer. * * Extensions that support reviving should have an `"onWebviewPanel:viewType"` activation event and - * make sure that [registerWebviewPanelSerializer](#registerWebviewPanelSerializer) is called during activation. + * make sure that {@link registerWebviewPanelSerializer} is called during activation. * * Only a single serializer may be registered at a time for a given `viewType`. * @@ -8888,7 +8936,7 @@ declare module 'vscode' { * * Normally the webview's html context is created when the view becomes visible * and destroyed when it is hidden. Extensions that have complex state - * or UI can set the `retainContextWhenHidden` to make VS Code keep the webview + * or UI can set the `retainContextWhenHidden` to make the editor keep the webview * context around, even when the webview moves to a background tab. When a webview using * `retainContextWhenHidden` becomes hidden, its scripts and other dynamic content are suspended. * When the view becomes visible again, the context is automatically restored @@ -8905,9 +8953,9 @@ declare module 'vscode' { /** * Register a provider for custom editors for the `viewType` contributed by the `customEditors` extension point. * - * When a custom editor is opened, VS Code fires an `onCustomEditor:viewType` activation event. Your extension - * must register a [`CustomTextEditorProvider`](#CustomTextEditorProvider), [`CustomReadonlyEditorProvider`](#CustomReadonlyEditorProvider), - * [`CustomEditorProvider`](#CustomEditorProvider)for `viewType` as part of activation. + * When a custom editor is opened, an `onCustomEditor:viewType` activation event is fired. Your extension + * must register a {@link CustomTextEditorProvider `CustomTextEditorProvider`}, {@link CustomReadonlyEditorProvider `CustomReadonlyEditorProvider`}, + * {@link CustomEditorProvider `CustomEditorProvider`}for `viewType` as part of activation. * * @param viewType Unique identifier for the custom editor provider. This should match the `viewType` from the * `customEditors` contribution point. @@ -8928,7 +8976,7 @@ declare module 'vscode' { * Indicates that the provider allows multiple editor instances to be open at the same time for * the same resource. * - * By default, VS Code only allows one editor instance to be open at a time for each resource. If the + * By default, the editor only allows one editor instance to be open at a time for each resource. If the * user tries to open a second editor instance for the resource, the first one is instead moved to where * the second one was to be opened. * @@ -8949,8 +8997,8 @@ declare module 'vscode' { /** * Register a file decoration provider. * - * @param provider A [FileDecorationProvider](#FileDecorationProvider). - * @return A [disposable](#Disposable) that unregisters the provider. + * @param provider A {@link FileDecorationProvider}. + * @return A {@link Disposable} that unregisters the provider. */ export function registerFileDecorationProvider(provider: FileDecorationProvider): Disposable; @@ -8961,13 +9009,13 @@ declare module 'vscode' { export let activeColorTheme: ColorTheme; /** - * An [event](#Event) which fires when the active color theme is changed or has changes. + * An {@link Event} which fires when the active color theme is changed or has changes. */ export const onDidChangeActiveColorTheme: Event; } /** - * Options for creating a [TreeView](#TreeView) + * Options for creating a {@link TreeView} */ export interface TreeViewOptions { @@ -8990,7 +9038,7 @@ declare module 'vscode' { } /** - * The event that is fired when an element in the [TreeView](#TreeView) is expanded or collapsed + * The event that is fired when an element in the {@link TreeView} is expanded or collapsed */ export interface TreeViewExpansionEvent { @@ -9002,7 +9050,7 @@ declare module 'vscode' { } /** - * The event that is fired when there is a change in [tree view's selection](#TreeView.selection) + * The event that is fired when there is a change in {@link TreeView.selection tree view's selection} */ export interface TreeViewSelectionChangeEvent { @@ -9014,12 +9062,12 @@ declare module 'vscode' { } /** - * The event that is fired when there is a change in [tree view's visibility](#TreeView.visible) + * The event that is fired when there is a change in {@link TreeView.visible tree view's visibility} */ export interface TreeViewVisibilityChangeEvent { /** - * `true` if the [tree view](#TreeView) is visible otherwise `false`. + * `true` if the {@link TreeView tree view} is visible otherwise `false`. */ readonly visible: boolean; @@ -9046,17 +9094,17 @@ declare module 'vscode' { readonly selection: T[]; /** - * Event that is fired when the [selection](#TreeView.selection) has changed + * Event that is fired when the {@link TreeView.selection selection} has changed */ readonly onDidChangeSelection: Event>; /** - * `true` if the [tree view](#TreeView) is visible otherwise `false`. + * `true` if the {@link TreeView tree view} is visible otherwise `false`. */ readonly visible: boolean; /** - * Event that is fired when [visibility](#TreeView.visible) has changed + * Event that is fired when {@link TreeView.visible visibility} has changed */ readonly onDidChangeVisibility: Event; @@ -9088,7 +9136,7 @@ declare module 'vscode' { * In order to expand the revealed element, set the option `expand` to `true`. To expand recursively set `expand` to the number of levels to expand. * **NOTE:** You can expand only to 3 levels maximum. * - * **NOTE:** The [TreeDataProvider](#TreeDataProvider) that the `TreeView` [is registered with](#window.createTreeView) with must implement [getParent](#TreeDataProvider.getParent) method to access this API. + * **NOTE:** The {@link TreeDataProvider} that the `TreeView` {@link window.createTreeView is registered with} with must implement {@link TreeDataProvider.getParent getParent} method to access this API. */ reveal(element: T, options?: { select?: boolean, focus?: boolean, expand?: boolean | number }): Thenable; } @@ -9105,10 +9153,10 @@ declare module 'vscode' { onDidChangeTreeData?: Event; /** - * Get [TreeItem](#TreeItem) representation of the `element` + * Get {@link TreeItem} representation of the `element` * - * @param element The element for which [TreeItem](#TreeItem) representation is asked for. - * @return [TreeItem](#TreeItem) representation of the element + * @param element The element for which {@link TreeItem} representation is asked for. + * @return {@link TreeItem} representation of the element */ getTreeItem(element: T): TreeItem | Thenable; @@ -9124,7 +9172,7 @@ declare module 'vscode' { * Optional method to return the parent of `element`. * Return `null` or `undefined` if `element` is a child of root. * - * **NOTE:** This method should be implemented in order to access [reveal](#TreeView.reveal) API. + * **NOTE:** This method should be implemented in order to access {@link TreeView.reveal reveal} API. * * @param element The element for which the parent has to be returned. * @return Parent of `element`. @@ -9132,8 +9180,8 @@ declare module 'vscode' { getParent?(element: T): ProviderResult; /** - * Called on hover to resolve the [TreeItem](#TreeItem.tooltip) property if it is undefined. - * Called on tree item click/open to resolve the [TreeItem](#TreeItem.command) property if it is undefined. + * Called on hover to resolve the {@link TreeItem.tooltip TreeItem} property if it is undefined. + * Called on tree item click/open to resolve the {@link TreeItem.command TreeItem} property if it is undefined. * Only properties that were undefined can be resolved in `resolveTreeItem`. * Functionality may be expanded later to include being called to resolve other missing * properties on selection and/or on open. @@ -9157,7 +9205,7 @@ declare module 'vscode' { export class TreeItem { /** - * A human-readable string describing this item. When `falsy`, it is derived from [resourceUri](#TreeItem.resourceUri). + * A human-readable string describing this item. When `falsy`, it is derived from {@link TreeItem.resourceUri resourceUri}. */ label?: string | TreeItemLabel; @@ -9169,23 +9217,23 @@ declare module 'vscode' { id?: string; /** - * The icon path or [ThemeIcon](#ThemeIcon) for the tree item. - * When `falsy`, [Folder Theme Icon](#ThemeIcon.Folder) is assigned, if item is collapsible otherwise [File Theme Icon](#ThemeIcon.File). - * When a file or folder [ThemeIcon](#ThemeIcon) is specified, icon is derived from the current file icon theme for the specified theme icon using [resourceUri](#TreeItem.resourceUri) (if provided). + * The icon path or {@link ThemeIcon} for the tree item. + * When `falsy`, {@link ThemeIcon.Folder Folder Theme Icon} is assigned, if item is collapsible otherwise {@link ThemeIcon.File File Theme Icon}. + * When a file or folder {@link ThemeIcon} is specified, icon is derived from the current file icon theme for the specified theme icon using {@link TreeItem.resourceUri resourceUri} (if provided). */ iconPath?: string | Uri | { light: string | Uri; dark: string | Uri } | ThemeIcon; /** * A human-readable string which is rendered less prominent. - * When `true`, it is derived from [resourceUri](#TreeItem.resourceUri) and when `falsy`, it is not shown. + * When `true`, it is derived from {@link TreeItem.resourceUri resourceUri} and when `falsy`, it is not shown. */ description?: string | boolean; /** - * The [uri](#Uri) of the resource representing this item. + * The {@link Uri} of the resource representing this item. * - * Will be used to derive the [label](#TreeItem.label), when it is not provided. - * Will be used to derive the icon from current file icon theme, when [iconPath](#TreeItem.iconPath) has [ThemeIcon](#ThemeIcon) value. + * Will be used to derive the {@link TreeItem.label label}, when it is not provided. + * Will be used to derive the icon from current file icon theme, when {@link TreeItem.iconPath iconPath} has {@link ThemeIcon} value. */ resourceUri?: Uri; @@ -9195,7 +9243,7 @@ declare module 'vscode' { tooltip?: string | MarkdownString | undefined; /** - * The [command](#Command) that should be executed when the tree item is selected. + * The {@link Command} that should be executed when the tree item is selected. * * Please use `vscode.open` or `vscode.diff` as command IDs when the tree item is opening * something in the editor. Using these commands ensures that the resulting editor will @@ -9204,7 +9252,7 @@ declare module 'vscode' { command?: Command; /** - * [TreeItemCollapsibleState](#TreeItemCollapsibleState) of the tree item. + * {@link TreeItemCollapsibleState} of the tree item. */ collapsibleState?: TreeItemCollapsibleState; @@ -9237,13 +9285,13 @@ declare module 'vscode' { /** * @param label A human-readable string describing this item - * @param collapsibleState [TreeItemCollapsibleState](#TreeItemCollapsibleState) of the tree item. Default is [TreeItemCollapsibleState.None](#TreeItemCollapsibleState.None) + * @param collapsibleState {@link TreeItemCollapsibleState} of the tree item. Default is {@link TreeItemCollapsibleState.None} */ constructor(label: string | TreeItemLabel, collapsibleState?: TreeItemCollapsibleState); /** - * @param resourceUri The [uri](#Uri) of the resource representing this item. - * @param collapsibleState [TreeItemCollapsibleState](#TreeItemCollapsibleState) of the tree item. Default is [TreeItemCollapsibleState.None](#TreeItemCollapsibleState.None) + * @param resourceUri The {@link Uri} of the resource representing this item. + * @param collapsibleState {@link TreeItemCollapsibleState} of the tree item. Default is {@link TreeItemCollapsibleState.None} */ constructor(resourceUri: Uri, collapsibleState?: TreeItemCollapsibleState); } @@ -9267,12 +9315,12 @@ declare module 'vscode' { } /** - * Label describing the [Tree item](#TreeItem) + * Label describing the {@link TreeItem Tree item} */ export interface TreeItemLabel { /** - * A human-readable string describing the [Tree item](#TreeItem). + * A human-readable string describing the {@link TreeItem Tree item}. */ label: string; @@ -9330,6 +9378,13 @@ declare module 'vscode' { * as normal. */ hideFromUser?: boolean; + + /** + * A message to write to the terminal on first launch, note that this is not sent to the + * process but, rather written directly to the terminal. This supports escape sequences such + * a setting text style. + */ + message?: string; } /** @@ -9342,7 +9397,7 @@ declare module 'vscode' { name: string; /** - * An implementation of [Pseudoterminal](#Pseudoterminal) that allows an extension to + * An implementation of {@link Pseudoterminal} that allows an extension to * control a terminal. */ pty: Pseudoterminal; @@ -9354,7 +9409,7 @@ declare module 'vscode' { interface Pseudoterminal { /** * An event that when fired will write data to the terminal. Unlike - * [Terminal.sendText](#Terminal.sendText) which sends text to the underlying child + * {@link Terminal.sendText} which sends text to the underlying child * pseudo-device (the child), this will write the text to parent pseudo-device (the * _terminal_ itself). * @@ -9380,7 +9435,7 @@ declare module 'vscode' { onDidWrite: Event; /** - * An event that when fired allows overriding the [dimensions](#Pseudoterminal.setDimensions) of the + * An event that when fired allows overriding the {@link Pseudoterminal.setDimensions dimensions} of the * terminal. Note that when set, the overridden dimensions will only take effect when they * are lower than the actual dimensions of the terminal (ie. there will never be a scroll * bar). Set to `undefined` for the terminal to go back to the regular dimensions (fit to @@ -9449,7 +9504,7 @@ declare module 'vscode' { /** * Implement to handle incoming keystrokes in the terminal or when an extension calls - * [Terminal.sendText](#Terminal.sendText). `data` contains the keystrokes/text serialized into + * {@link Terminal.sendText}. `data` contains the keystrokes/text serialized into * their corresponding VT sequence representation. * * @param data The incoming data. @@ -9476,7 +9531,7 @@ declare module 'vscode' { * as the size of a terminal isn't known until it shows up in the user interface. * * When dimensions are overridden by - * [onDidOverrideDimensions](#Pseudoterminal.onDidOverrideDimensions), `setDimensions` will + * {@link Pseudoterminal.onDidOverrideDimensions onDidOverrideDimensions}, `setDimensions` will * continue to be called with the regular panel dimensions, allowing the extension continue * to react dimension changes. * @@ -9672,23 +9727,23 @@ declare module 'vscode' { /** * A light-weight user input UI that is initially not visible. After * configuring it through its properties the extension can make it - * visible by calling [QuickInput.show](#QuickInput.show). + * visible by calling {@link QuickInput.show}. * * There are several reasons why this UI might have to be hidden and - * the extension will be notified through [QuickInput.onDidHide](#QuickInput.onDidHide). - * (Examples include: an explicit call to [QuickInput.hide](#QuickInput.hide), + * the extension will be notified through {@link QuickInput.onDidHide}. + * (Examples include: an explicit call to {@link QuickInput.hide}, * the user pressing Esc, some other input UI opening, etc.) * * A user pressing Enter or some other gesture implying acceptance * of the current state does not automatically hide this UI component. * It is up to the extension to decide whether to accept the user's input - * and if the UI should indeed be hidden through a call to [QuickInput.hide](#QuickInput.hide). + * and if the UI should indeed be hidden through a call to {@link QuickInput.hide}. * * When the extension no longer needs this input UI, it should - * [QuickInput.dispose](#QuickInput.dispose) it to allow for freeing up + * {@link QuickInput.dispose} it to allow for freeing up * any resources associated with it. * - * See [QuickPick](#QuickPick) and [InputBox](#InputBox) for concrete UIs. + * See {@link QuickPick} and {@link InputBox} for concrete UIs. */ export interface QuickInput { @@ -9730,12 +9785,12 @@ declare module 'vscode' { /** * Makes the input UI visible in its current configuration. Any other input - * UI will first fire an [QuickInput.onDidHide](#QuickInput.onDidHide) event. + * UI will first fire an {@link QuickInput.onDidHide} event. */ show(): void; /** - * Hides this input UI. This will also fire an [QuickInput.onDidHide](#QuickInput.onDidHide) + * Hides this input UI. This will also fire an {@link QuickInput.onDidHide} * event. */ hide(): void; @@ -9744,8 +9799,8 @@ declare module 'vscode' { * An event signaling when this input UI is hidden. * * There are several reasons why this UI might have to be hidden and - * the extension will be notified through [QuickInput.onDidHide](#QuickInput.onDidHide). - * (Examples include: an explicit call to [QuickInput.hide](#QuickInput.hide), + * the extension will be notified through {@link QuickInput.onDidHide}. + * (Examples include: an explicit call to {@link QuickInput.hide}, * the user pressing Esc, some other input UI opening, etc.) */ onDidHide: Event; @@ -9760,14 +9815,14 @@ declare module 'vscode' { } /** - * A concrete [QuickInput](#QuickInput) to let the user pick an item from a + * A concrete {@link QuickInput} to let the user pick an item from a * list of items of type T. The items can be filtered through a filter text field and - * there is an option [canSelectMany](#QuickPick.canSelectMany) to allow for + * there is an option {@link QuickPick.canSelectMany canSelectMany} to allow for * selecting multiple items. * - * Note that in many cases the more convenient [window.showQuickPick](#window.showQuickPick) - * is easier to use. [window.createQuickPick](#window.createQuickPick) should be used - * when [window.showQuickPick](#window.showQuickPick) does not offer the required flexibility. + * Note that in many cases the more convenient {@link window.showQuickPick} + * is easier to use. {@link window.createQuickPick} should be used + * when {@link window.showQuickPick} does not offer the required flexibility. */ export interface QuickPick extends QuickInput { @@ -9794,7 +9849,7 @@ declare module 'vscode' { /** * Buttons for actions in the UI. */ - buttons: ReadonlyArray; + buttons: readonly QuickInputButton[]; /** * An event signaling when a button was triggered. @@ -9804,7 +9859,7 @@ declare module 'vscode' { /** * Items to pick from. */ - items: ReadonlyArray; + items: readonly T[]; /** * If multiple items can be selected at the same time. Defaults to false. @@ -9824,7 +9879,7 @@ declare module 'vscode' { /** * Active items. This can be read and updated by the extension. */ - activeItems: ReadonlyArray; + activeItems: readonly T[]; /** * An event signaling when the active items have changed. @@ -9834,7 +9889,7 @@ declare module 'vscode' { /** * Selected items. This can be read and updated by the extension. */ - selectedItems: ReadonlyArray; + selectedItems: readonly T[]; /** * An event signaling when the selected items have changed. @@ -9843,11 +9898,11 @@ declare module 'vscode' { } /** - * A concrete [QuickInput](#QuickInput) to let the user input a text value. + * A concrete {@link QuickInput} to let the user input a text value. * - * Note that in many cases the more convenient [window.showInputBox](#window.showInputBox) - * is easier to use. [window.createInputBox](#window.createInputBox) should be used - * when [window.showInputBox](#window.showInputBox) does not offer the required flexibility. + * Note that in many cases the more convenient {@link window.showInputBox} + * is easier to use. {@link window.createInputBox} should be used + * when {@link window.showInputBox} does not offer the required flexibility. */ export interface InputBox extends QuickInput { @@ -9879,7 +9934,7 @@ declare module 'vscode' { /** * Buttons for actions in the UI. */ - buttons: ReadonlyArray; + buttons: readonly QuickInputButton[]; /** * An event signaling when a button was triggered. @@ -9898,7 +9953,7 @@ declare module 'vscode' { } /** - * Button for an action in a [QuickPick](#QuickPick) or [InputBox](#InputBox). + * Button for an action in a {@link QuickPick} or {@link InputBox}. */ export interface QuickInputButton { @@ -9914,12 +9969,12 @@ declare module 'vscode' { } /** - * Predefined buttons for [QuickPick](#QuickPick) and [InputBox](#InputBox). + * Predefined buttons for {@link QuickPick} and {@link InputBox}. */ export class QuickInputButtons { /** - * A back button for [QuickPick](#QuickPick) and [InputBox](#InputBox). + * A back button for {@link QuickPick} and {@link InputBox}. * * When a navigation 'back' button is needed this one should be used for consistency. * It comes with a predefined icon, tooltip and location. @@ -9933,7 +9988,7 @@ declare module 'vscode' { } /** - * An event describing an individual change in the text of a [document](#TextDocument). + * An event describing an individual change in the text of a {@link TextDocument document}. */ export interface TextDocumentContentChangeEvent { /** @@ -9955,7 +10010,7 @@ declare module 'vscode' { } /** - * An event describing a transactional [document](#TextDocument) change. + * An event describing a transactional {@link TextDocument document} change. */ export interface TextDocumentChangeEvent { @@ -9967,7 +10022,7 @@ declare module 'vscode' { /** * An array of content changes. */ - readonly contentChanges: ReadonlyArray; + readonly contentChanges: readonly TextDocumentContentChangeEvent[]; } /** @@ -9993,11 +10048,11 @@ declare module 'vscode' { } /** - * An event that is fired when a [document](#TextDocument) will be saved. + * An event that is fired when a {@link TextDocument document} will be saved. * * To make modifications to the document before it is being saved, call the - * [`waitUntil`](#TextDocumentWillSaveEvent.waitUntil)-function with a thenable - * that resolves to an array of [text edits](#TextEdit). + * {@link TextDocumentWillSaveEvent.waitUntil `waitUntil`}-function with a thenable + * that resolves to an array of {@link TextEdit text edits}. */ export interface TextDocumentWillSaveEvent { @@ -10012,7 +10067,7 @@ declare module 'vscode' { readonly reason: TextDocumentSaveReason; /** - * Allows to pause the event loop and to apply [pre-save-edits](#TextEdit). + * Allows to pause the event loop and to apply {@link TextEdit pre-save-edits}. * Edits of subsequent calls to this function will be applied in order. The * edits will be *ignored* if concurrent modifications of the document happened. * @@ -10029,7 +10084,7 @@ declare module 'vscode' { * }) * ``` * - * @param thenable A thenable that resolves to [pre-save-edits](#TextEdit). + * @param thenable A thenable that resolves to {@link TextEdit pre-save-edits}. */ waitUntil(thenable: Thenable): void; @@ -10047,18 +10102,18 @@ declare module 'vscode' { * An event that is fired when files are going to be created. * * To make modifications to the workspace before the files are created, - * call the [`waitUntil](#FileWillCreateEvent.waitUntil)-function with a - * thenable that resolves to a [workspace edit](#WorkspaceEdit). + * call the {@link FileWillCreateEvent.waitUntil `waitUntil`}-function with a + * thenable that resolves to a {@link WorkspaceEdit workspace edit}. */ export interface FileWillCreateEvent { /** * The files that are going to be created. */ - readonly files: ReadonlyArray; + readonly files: readonly Uri[]; /** - * Allows to pause the event and to apply a [workspace edit](#WorkspaceEdit). + * Allows to pause the event and to apply a {@link WorkspaceEdit workspace edit}. * * *Note:* This function can only be called during event dispatch and not * in an asynchronous manner: @@ -10095,25 +10150,25 @@ declare module 'vscode' { /** * The files that got created. */ - readonly files: ReadonlyArray; + readonly files: readonly Uri[]; } /** * An event that is fired when files are going to be deleted. * * To make modifications to the workspace before the files are deleted, - * call the [`waitUntil](#FileWillCreateEvent.waitUntil)-function with a - * thenable that resolves to a [workspace edit](#WorkspaceEdit). + * call the {@link FileWillCreateEvent.waitUntil `waitUntil}-function with a + * thenable that resolves to a {@link WorkspaceEdit workspace edit}. */ export interface FileWillDeleteEvent { /** * The files that are going to be deleted. */ - readonly files: ReadonlyArray; + readonly files: readonly Uri[]; /** - * Allows to pause the event and to apply a [workspace edit](#WorkspaceEdit). + * Allows to pause the event and to apply a {@link WorkspaceEdit workspace edit}. * * *Note:* This function can only be called during event dispatch and not * in an asynchronous manner: @@ -10150,25 +10205,25 @@ declare module 'vscode' { /** * The files that got deleted. */ - readonly files: ReadonlyArray; + readonly files: readonly Uri[]; } /** * An event that is fired when files are going to be renamed. * * To make modifications to the workspace before the files are renamed, - * call the [`waitUntil](#FileWillCreateEvent.waitUntil)-function with a - * thenable that resolves to a [workspace edit](#WorkspaceEdit). + * call the {@link FileWillCreateEvent.waitUntil `waitUntil}-function with a + * thenable that resolves to a {@link WorkspaceEdit workspace edit}. */ export interface FileWillRenameEvent { /** * The files that are going to be renamed. */ - readonly files: ReadonlyArray<{ oldUri: Uri, newUri: Uri }>; + readonly files: ReadonlyArray<{ readonly oldUri: Uri, readonly newUri: Uri }>; /** - * Allows to pause the event and to apply a [workspace edit](#WorkspaceEdit). + * Allows to pause the event and to apply a {@link WorkspaceEdit workspace edit}. * * *Note:* This function can only be called during event dispatch and not * in an asynchronous manner: @@ -10205,22 +10260,22 @@ declare module 'vscode' { /** * The files that got renamed. */ - readonly files: ReadonlyArray<{ oldUri: Uri, newUri: Uri }>; + readonly files: ReadonlyArray<{ readonly oldUri: Uri, readonly newUri: Uri }>; } /** - * An event describing a change to the set of [workspace folders](#workspace.workspaceFolders). + * An event describing a change to the set of {@link workspace.workspaceFolders workspace folders}. */ export interface WorkspaceFoldersChangeEvent { /** * Added workspace folders. */ - readonly added: ReadonlyArray; + readonly added: readonly WorkspaceFolder[]; /** * Removed workspace folders. */ - readonly removed: ReadonlyArray; + readonly removed: readonly WorkspaceFolder[]; } /** @@ -10232,14 +10287,14 @@ declare module 'vscode' { /** * The associated uri for this workspace folder. * - * *Note:* The [Uri](#Uri)-type was intentionally chosen such that future releases of the editor can support + * *Note:* The {@link Uri}-type was intentionally chosen such that future releases of the editor can support * workspace folders that are not stored on the local disk, e.g. `ftp://server/workspaces/foo`. */ readonly uri: Uri; /** * The name of this workspace folder. Defaults to - * the basename of its [uri-path](#Uri.path) + * the basename of its {@link Uri.path uri-path} */ readonly name: string; @@ -10261,14 +10316,14 @@ declare module 'vscode' { * Refer to https://code.visualstudio.com/docs/editor/workspaces for more information on * the concept of workspaces in VS Code. * - * The workspace offers support for [listening](#workspace.createFileSystemWatcher) to fs - * events and for [finding](#workspace.findFiles) files. Both perform well and run _outside_ + * The workspace offers support for {@link workspace.createFileSystemWatcher listening} to fs + * events and for {@link workspace.findFiles finding} files. Both perform well and run _outside_ * the editor-process so that they should be always used instead of nodejs-equivalents. */ export namespace workspace { /** - * A [file system](#FileSystem) instance that allows to interact with local and remote + * A {@link FileSystem file system} instance that allows to interact with local and remote * files, e.g. `vscode.workspace.fs.readDirectory(someUri)` allows to retrieve all entries * of a directory or `vscode.workspace.fs.stat(anotherUri)` returns the meta data for a * file. @@ -10282,12 +10337,12 @@ declare module 'vscode' { * Refer to https://code.visualstudio.com/docs/editor/workspaces for more information * on workspaces in VS Code. * - * @deprecated Use [`workspaceFolders`](#workspace.workspaceFolders) instead. + * @deprecated Use {@link workspace.workspaceFolders `workspaceFolders`} instead. */ export const rootPath: string | undefined; /** - * List of workspace folders that are open in VS Code. `undefined when no workspace + * List of workspace folders that are open in VS Code. `undefined` when no workspace * has been opened. * * Refer to https://code.visualstudio.com/docs/editor/workspaces for more information @@ -10295,7 +10350,7 @@ declare module 'vscode' { * * *Note* that the first entry corresponds to the value of `rootPath`. */ - export const workspaceFolders: ReadonlyArray | undefined; + export const workspaceFolders: readonly WorkspaceFolder[] | undefined; /** * The name of the workspace. `undefined` when no workspace @@ -10346,7 +10401,7 @@ declare module 'vscode' { export const onDidChangeWorkspaceFolders: Event; /** - * Returns the [workspace folder](#WorkspaceFolder) that contains a given uri. + * Returns the {@link WorkspaceFolder workspace folder} that contains a given uri. * * returns `undefined` when the given uri doesn't match any workspace folder * * returns the *input* when the given uri is a workspace folder itself * @@ -10358,10 +10413,10 @@ declare module 'vscode' { /** * Returns a path that is relative to the workspace folder or folders. * - * When there are no [workspace folders](#workspace.workspaceFolders) or when the path + * When there are no {@link workspace.workspaceFolders workspace folders} or when the path * is not contained in them, the input is returned. * - * @param pathOrUri A path or uri. When a uri is given its [fsPath](#Uri.fsPath) is used. + * @param pathOrUri A path or uri. When a uri is given its {@link Uri.fsPath fsPath} is used. * @param includeWorkspaceFolder When `true` and when the given path is contained inside a * workspace folder the name of the workspace is prepended. Defaults to `true` when there are * multiple workspace folders and `false` otherwise. @@ -10370,7 +10425,7 @@ declare module 'vscode' { export function asRelativePath(pathOrUri: string | Uri, includeWorkspaceFolder?: boolean): string; /** - * This method replaces `deleteCount` [workspace folders](#workspace.workspaceFolders) starting at index `start` + * This method replaces `deleteCount` {@link workspace.workspaceFolders workspace folders} starting at index `start` * by an optional set of `workspaceFoldersToAdd` on the `vscode.workspace.workspaceFolders` array. This "splice" * behavior can be used to add, remove and change workspace folders in a single operation. * @@ -10378,7 +10433,7 @@ declare module 'vscode' { * one that called this method) will be terminated and restarted so that the (deprecated) `rootPath` property is * updated to point to the first workspace folder. * - * Use the [`onDidChangeWorkspaceFolders()`](#onDidChangeWorkspaceFolders) event to get notified when the + * Use the {@link onDidChangeWorkspaceFolders `onDidChangeWorkspaceFolders()`} event to get notified when the * workspace folders have been updated. * * **Example:** adding a new workspace folder at the end of workspace folders @@ -10399,10 +10454,10 @@ declare module 'vscode' { * It is valid to remove an existing workspace folder and add it again with a different name * to rename that folder. * - * **Note:** it is not valid to call [updateWorkspaceFolders()](#updateWorkspaceFolders) multiple times - * without waiting for the [`onDidChangeWorkspaceFolders()`](#onDidChangeWorkspaceFolders) to fire. + * **Note:** it is not valid to call {@link updateWorkspaceFolders updateWorkspaceFolders()} multiple times + * without waiting for the {@link onDidChangeWorkspaceFolders `onDidChangeWorkspaceFolders()`} to fire. * - * @param start the zero-based location in the list of currently opened [workspace folders](#WorkspaceFolder) + * @param start the zero-based location in the list of currently opened {@link WorkspaceFolder workspace folders} * from which to start deleting workspace folders. * @param deleteCount the optional number of workspace folders to remove. * @param workspaceFoldersToAdd the optional variable set of workspace folders to add in place of the deleted ones. @@ -10418,12 +10473,12 @@ declare module 'vscode' { * A glob pattern that filters the file events on their absolute path must be provided. Optionally, * flags to ignore certain kinds of events can be provided. To stop listening to events the watcher must be disposed. * - * *Note* that only files within the current [workspace folders](#workspace.workspaceFolders) can be watched. + * *Note* that only files within the current {@link workspace.workspaceFolders workspace folders} can be watched. * *Note* that when watching for file changes such as '**​/*.js', notifications will not be sent when a parent folder is * moved or deleted (this is a known limitation of the current implementation and may change in the future). * - * @param globPattern A [glob pattern](#GlobPattern) that is applied to the absolute paths of created, changed, - * and deleted files. Use a [relative pattern](#RelativePattern) to limit events to a certain [workspace folder](#WorkspaceFolder). + * @param globPattern A {@link GlobPattern glob pattern} that is applied to the absolute paths of created, changed, + * and deleted files. Use a {@link RelativePattern relative pattern} to limit events to a certain {@link WorkspaceFolder workspace folder}. * @param ignoreCreateEvents Ignore when files have been created. * @param ignoreChangeEvents Ignore when files have been changed. * @param ignoreDeleteEvents Ignore when files have been deleted. @@ -10432,21 +10487,21 @@ declare module 'vscode' { export function createFileSystemWatcher(globPattern: GlobPattern, ignoreCreateEvents?: boolean, ignoreChangeEvents?: boolean, ignoreDeleteEvents?: boolean): FileSystemWatcher; /** - * Find files across all [workspace folders](#workspace.workspaceFolders) in the workspace. + * Find files across all {@link workspace.workspaceFolders workspace folders} in the workspace. * * @example * findFiles('**​/*.js', '**​/node_modules/**', 10) * - * @param include A [glob pattern](#GlobPattern) that defines the files to search for. The glob pattern - * will be matched against the file paths of resulting matches relative to their workspace. Use a [relative pattern](#RelativePattern) - * to restrict the search results to a [workspace folder](#WorkspaceFolder). - * @param exclude A [glob pattern](#GlobPattern) that defines files and folders to exclude. The glob pattern - * will be matched against the file paths of resulting matches relative to their workspace. When `undefined` only default excludes will - * apply, when `null` no excludes will apply. + * @param include A {@link GlobPattern glob pattern} that defines the files to search for. The glob pattern + * will be matched against the file paths of resulting matches relative to their workspace. Use a {@link RelativePattern relative pattern} + * to restrict the search results to a {@link WorkspaceFolder workspace folder}. + * @param exclude A {@link GlobPattern glob pattern} that defines files and folders to exclude. The glob pattern + * will be matched against the file paths of resulting matches relative to their workspace. When `undefined`, default excludes and the user's + * configured excludes will apply. When `null`, no excludes will apply. * @param maxResults An upper-bound for the result. * @param token A token that can be used to signal cancellation to the underlying search engine. * @return A thenable that resolves to an array of resource identifiers. Will return no results if no - * [workspace folders](#workspace.workspaceFolders) are opened. + * {@link workspace.workspaceFolders workspace folders} are opened. */ export function findFiles(include: GlobPattern, exclude?: GlobPattern | null, maxResults?: number, token?: CancellationToken): Thenable; @@ -10460,7 +10515,7 @@ declare module 'vscode' { /** * Make changes to one or many resources or create, delete, and rename resources as defined by the given - * [workspace edit](#WorkspaceEdit). + * {@link WorkspaceEdit workspace edit}. * * All changes of a workspace edit are applied in the same order in which they have been added. If * multiple textual inserts are made at the same position, these strings appear in the resulting text @@ -10477,36 +10532,36 @@ declare module 'vscode' { export function applyEdit(edit: WorkspaceEdit): Thenable; /** - * All text documents currently known to the system. + * All text documents currently known to the editor. */ - export const textDocuments: ReadonlyArray; + export const textDocuments: readonly TextDocument[]; /** * Opens a document. Will return early if this document is already open. Otherwise - * the document is loaded and the [didOpen](#workspace.onDidOpenTextDocument)-event fires. + * the document is loaded and the {@link workspace.onDidOpenTextDocument didOpen}-event fires. * - * The document is denoted by an [uri](#Uri). Depending on the [scheme](#Uri.scheme) the + * The document is denoted by an {@link Uri}. Depending on the {@link Uri.scheme scheme} the * following rules apply: * * `file`-scheme: Open a file on disk, will be rejected if the file does not exist or cannot be loaded. * * `untitled`-scheme: A new file that should be saved on disk, e.g. `untitled:c:\frodo\new.js`. The language * will be derived from the file name. - * * For all other schemes contributed [text document content providers](#TextDocumentContentProvider) and - * [file system providers](#FileSystemProvider) are consulted. + * * For all other schemes contributed {@link TextDocumentContentProvider text document content providers} and + * {@link FileSystemProvider file system providers} are consulted. * * *Note* that the lifecycle of the returned document is owned by the editor and not by the extension. That means an - * [`onDidClose`](#workspace.onDidCloseTextDocument)-event can occur at any time after opening it. + * {@link workspace.onDidCloseTextDocument `onDidClose`}-event can occur at any time after opening it. * * @param uri Identifies the resource to open. - * @return A promise that resolves to a [document](#TextDocument). + * @return A promise that resolves to a {@link TextDocument document}. */ export function openTextDocument(uri: Uri): Thenable; /** * A short-hand for `openTextDocument(Uri.file(fileName))`. * - * @see [openTextDocument](#openTextDocument) + * @see {@link openTextDocument} * @param fileName A name of a file on disk. - * @return A promise that resolves to a [document](#TextDocument). + * @return A promise that resolves to a {@link TextDocument document}. */ export function openTextDocument(fileName: string): Thenable; @@ -10516,7 +10571,7 @@ declare module 'vscode' { * specify the *language* and/or the *content* of the document. * * @param options Options to control how the document will be created. - * @return A promise that resolves to a [document](#TextDocument). + * @return A promise that resolves to a {@link TextDocument document}. */ export function openTextDocument(options?: { language?: string; content?: string; }): Thenable; @@ -10527,30 +10582,30 @@ declare module 'vscode' { * * @param scheme The uri-scheme to register for. * @param provider A content provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerTextDocumentContentProvider(scheme: string, provider: TextDocumentContentProvider): Disposable; /** - * An event that is emitted when a [text document](#TextDocument) is opened or when the language id - * of a text document [has been changed](#languages.setTextDocumentLanguage). + * An event that is emitted when a {@link TextDocument text document} is opened or when the language id + * of a text document {@link languages.setTextDocumentLanguage has been changed}. * - * To add an event listener when a visible text document is opened, use the [TextEditor](#TextEditor) events in the - * [window](#window) namespace. Note that: + * To add an event listener when a visible text document is opened, use the {@link TextEditor} events in the + * {@link window} namespace. Note that: * - * - The event is emitted before the [document](#TextDocument) is updated in the - * [active text editor](#window.activeTextEditor) - * - When a [text document](#TextDocument) is already open (e.g.: open in another [visible text editor](#window.visibleTextEditors)) this event is not emitted + * - The event is emitted before the {@link TextDocument document} is updated in the + * {@link window.activeTextEditor active text editor} + * - When a {@link TextDocument text document} is already open (e.g.: open in another {@link window.visibleTextEditors visible text editor}) this event is not emitted * */ export const onDidOpenTextDocument: Event; /** - * An event that is emitted when a [text document](#TextDocument) is disposed or when the language id - * of a text document [has been changed](#languages.setTextDocumentLanguage). + * An event that is emitted when a {@link TextDocument text document} is disposed or when the language id + * of a text document {@link languages.setTextDocumentLanguage has been changed}. * * *Note 1:* There is no guarantee that this event fires when an editor tab is closed, use the - * [`onDidChangeVisibleTextEditors`](#window.onDidChangeVisibleTextEditors)-event to know when editors change. + * {@link window.onDidChangeVisibleTextEditors `onDidChangeVisibleTextEditors`}-event to know when editors change. * * *Note 2:* A document can be open but not shown in an editor which means this event can fire * for a document that has not been shown in an editor. @@ -10558,19 +10613,19 @@ declare module 'vscode' { export const onDidCloseTextDocument: Event; /** - * An event that is emitted when a [text document](#TextDocument) is changed. This usually happens - * when the [contents](#TextDocument.getText) changes but also when other things like the - * [dirty](#TextDocument.isDirty)-state changes. + * An event that is emitted when a {@link TextDocument text document} is changed. This usually happens + * when the {@link TextDocument.getText contents} changes but also when other things like the + * {@link TextDocument.isDirty dirty}-state changes. */ export const onDidChangeTextDocument: Event; /** - * An event that is emitted when a [text document](#TextDocument) will be saved to disk. + * An event that is emitted when a {@link TextDocument text document} will be saved to disk. * * *Note 1:* Subscribers can delay saving by registering asynchronous work. For the sake of data integrity the editor * might save without firing this event. For instance when shutting down with dirty files. * - * *Note 2:* Subscribers are called sequentially and they can [delay](#TextDocumentWillSaveEvent.waitUntil) saving + * *Note 2:* Subscribers are called sequentially and they can {@link TextDocumentWillSaveEvent.waitUntil delay} saving * by registering asynchronous work. Protection against misbehaving listeners is implemented as such: * * there is an overall time budget that all listeners share and if that is exhausted no further listener is called * * listeners that take a long time or produce errors frequently will not be called anymore @@ -10580,7 +10635,7 @@ declare module 'vscode' { export const onWillSaveTextDocument: Event; /** - * An event that is emitted when a [text document](#TextDocument) is saved to disk. + * An event that is emitted when a {@link TextDocument text document} is saved to disk. */ export const onDidSaveTextDocument: Event; @@ -10588,9 +10643,9 @@ declare module 'vscode' { * An event that is emitted when files are being created. * * *Note 1:* This event is triggered by user gestures, like creating a file from the - * explorer, or from the [`workspace.applyEdit`](#workspace.applyEdit)-api. This event is *not* fired when + * explorer, or from the {@link workspace.applyEdit `workspace.applyEdit`}-api. This event is *not* fired when * files change on disk, e.g triggered by another application, or when using the - * [`workspace.fs`](#FileSystem)-api. + * {@link FileSystem `workspace.fs`}-api. * * *Note 2:* When this event is fired, edits to files that are are being created cannot be applied. */ @@ -10600,9 +10655,9 @@ declare module 'vscode' { * An event that is emitted when files have been created. * * *Note:* This event is triggered by user gestures, like creating a file from the - * explorer, or from the [`workspace.applyEdit`](#workspace.applyEdit)-api, but this event is *not* fired when + * explorer, or from the {@link workspace.applyEdit `workspace.applyEdit`}-api, but this event is *not* fired when * files change on disk, e.g triggered by another application, or when using the - * [`workspace.fs`](#FileSystem)-api. + * {@link FileSystem `workspace.fs`}-api. */ export const onDidCreateFiles: Event; @@ -10610,9 +10665,9 @@ declare module 'vscode' { * An event that is emitted when files are being deleted. * * *Note 1:* This event is triggered by user gestures, like deleting a file from the - * explorer, or from the [`workspace.applyEdit`](#workspace.applyEdit)-api, but this event is *not* fired when + * explorer, or from the {@link workspace.applyEdit `workspace.applyEdit`}-api, but this event is *not* fired when * files change on disk, e.g triggered by another application, or when using the - * [`workspace.fs`](#FileSystem)-api. + * {@link FileSystem `workspace.fs`}-api. * * *Note 2:* When deleting a folder with children only one event is fired. */ @@ -10622,9 +10677,9 @@ declare module 'vscode' { * An event that is emitted when files have been deleted. * * *Note 1:* This event is triggered by user gestures, like deleting a file from the - * explorer, or from the [`workspace.applyEdit`](#workspace.applyEdit)-api, but this event is *not* fired when + * explorer, or from the {@link workspace.applyEdit `workspace.applyEdit`}-api, but this event is *not* fired when * files change on disk, e.g triggered by another application, or when using the - * [`workspace.fs`](#FileSystem)-api. + * {@link FileSystem `workspace.fs`}-api. * * *Note 2:* When deleting a folder with children only one event is fired. */ @@ -10634,9 +10689,9 @@ declare module 'vscode' { * An event that is emitted when files are being renamed. * * *Note 1:* This event is triggered by user gestures, like renaming a file from the - * explorer, and from the [`workspace.applyEdit`](#workspace.applyEdit)-api, but this event is *not* fired when + * explorer, and from the {@link workspace.applyEdit `workspace.applyEdit`}-api, but this event is *not* fired when * files change on disk, e.g triggered by another application, or when using the - * [`workspace.fs`](#FileSystem)-api. + * {@link FileSystem `workspace.fs`}-api. * * *Note 2:* When renaming a folder with children only one event is fired. */ @@ -10646,9 +10701,9 @@ declare module 'vscode' { * An event that is emitted when files have been renamed. * * *Note 1:* This event is triggered by user gestures, like renaming a file from the - * explorer, and from the [`workspace.applyEdit`](#workspace.applyEdit)-api, but this event is *not* fired when + * explorer, and from the {@link workspace.applyEdit `workspace.applyEdit`}-api, but this event is *not* fired when * files change on disk, e.g triggered by another application, or when using the - * [`workspace.fs`](#FileSystem)-api. + * {@link FileSystem `workspace.fs`}-api. * * *Note 2:* When renaming a folder with children only one event is fired. */ @@ -10670,7 +10725,7 @@ declare module 'vscode' { export function getConfiguration(section?: string | undefined, scope?: ConfigurationScope | null): WorkspaceConfiguration; /** - * An event that is emitted when the [configuration](#WorkspaceConfiguration) changed. + * An event that is emitted when the {@link WorkspaceConfiguration configuration} changed. */ export const onDidChangeConfiguration: Event; @@ -10681,7 +10736,7 @@ declare module 'vscode' { * * @param type The task kind type this provider is registered for. * @param provider A task provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerTaskProvider(type: string, provider: TaskProvider): Disposable; @@ -10691,19 +10746,29 @@ declare module 'vscode' { * There can only be one provider per scheme and an error is being thrown when a scheme * has been claimed by another provider or when it is reserved. * - * @param scheme The uri-[scheme](#Uri.scheme) the provider registers for. + * @param scheme The uri-{@link Uri.scheme scheme} the provider registers for. * @param provider The filesystem provider. * @param options Immutable metadata about the provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerFileSystemProvider(scheme: string, provider: FileSystemProvider, options?: { readonly isCaseSensitive?: boolean, readonly isReadonly?: boolean }): Disposable; + + /** + * When true, the user has explicitly trusted the contents of the workspace. + */ + export const isTrusted: boolean; + + /** + * Event that fires when the current workspace has been trusted. + */ + export const onDidGrantWorkspaceTrust: Event; } /** * The configuration scope which can be a * a 'resource' or a languageId or both or - * a '[TextDocument](#TextDocument)' or - * a '[WorkspaceFolder](#WorkspaceFolder)' + * a '{@link TextDocument}' or + * a '{@link WorkspaceFolder}' */ export type ConfigurationScope = Uri | TextDocument | WorkspaceFolder | { uri?: Uri, languageId: string }; @@ -10733,7 +10798,7 @@ declare module 'vscode' { * * The editor provides an API that makes it simple to provide such common features by having all UI and actions already in place and * by allowing you to participate by providing data only. For instance, to contribute a hover all you have to do is provide a function - * that can be called with a [TextDocument](#TextDocument) and a [Position](#Position) returning hover info. The rest, like tracking the + * that can be called with a {@link TextDocument} and a {@link Position} returning hover info. The rest, like tracking the * mouse, positioning the hover, keeping the hover stable etc. is taken care of by the editor. * * ```javascript @@ -10744,11 +10809,11 @@ declare module 'vscode' { * }); * ``` * - * Registration is done using a [document selector](#DocumentSelector) which is either a language id, like `javascript` or - * a more complex [filter](#DocumentFilter) like `{ language: 'typescript', scheme: 'file' }`. Matching a document against such - * a selector will result in a [score](#languages.match) that is used to determine if and how a provider shall be used. When - * scores are equal the provider that came last wins. For features that allow full arity, like [hover](#languages.registerHoverProvider), - * the score is only checked to be `>0`, for other features, like [IntelliSense](#languages.registerCompletionItemProvider) the + * Registration is done using a {@link DocumentSelector document selector} which is either a language id, like `javascript` or + * a more complex {@link DocumentFilter filter} like `{ language: 'typescript', scheme: 'file' }`. Matching a document against such + * a selector will result in a {@link languages.match score} that is used to determine if and how a provider shall be used. When + * scores are equal the provider that came last wins. For features that allow full arity, like {@link languages.registerHoverProvider hover}, + * the score is only checked to be `>0`, for other features, like {@link languages.registerCompletionItemProvider IntelliSense} the * score is used for determining the order in which providers are asked to participate. */ export namespace languages { @@ -10760,11 +10825,11 @@ declare module 'vscode' { export function getLanguages(): Thenable; /** - * Set (and change) the [language](#TextDocument.languageId) that is associated + * Set (and change) the {@link TextDocument.languageId language} that is associated * with the given document. * - * *Note* that calling this function will trigger the [`onDidCloseTextDocument`](#workspace.onDidCloseTextDocument) event - * followed by the [`onDidOpenTextDocument`](#workspace.onDidOpenTextDocument) event. + * *Note* that calling this function will trigger the {@link workspace.onDidCloseTextDocument `onDidCloseTextDocument`} event + * followed by the {@link workspace.onDidOpenTextDocument `onDidOpenTextDocument`} event. * * @param document The document which language is to be changed * @param languageId The new language identifier. @@ -10773,13 +10838,13 @@ declare module 'vscode' { export function setTextDocumentLanguage(document: TextDocument, languageId: string): Thenable; /** - * Compute the match between a document [selector](#DocumentSelector) and a document. Values + * Compute the match between a document {@link DocumentSelector selector} and a document. Values * greater than zero mean the selector matches the document. * * A match is computed according to these rules: - * 1. When [`DocumentSelector`](#DocumentSelector) is an array, compute the match for each contained `DocumentFilter` or language identifier and take the maximum value. - * 2. A string will be desugared to become the `language`-part of a [`DocumentFilter`](#DocumentFilter), so `"fooLang"` is like `{ language: "fooLang" }`. - * 3. A [`DocumentFilter`](#DocumentFilter) will be matched against the document by comparing its parts with the document. The following rules apply: + * 1. When {@link DocumentSelector `DocumentSelector`} is an array, compute the match for each contained `DocumentFilter` or language identifier and take the maximum value. + * 2. A string will be desugared to become the `language`-part of a {@link DocumentFilter `DocumentFilter`}, so `"fooLang"` is like `{ language: "fooLang" }`. + * 3. A {@link DocumentFilter `DocumentFilter`} will be matched against the document by comparing its parts with the document. The following rules apply: * 1. When the `DocumentFilter` is empty (`{}`) the result is `0` * 2. When `scheme`, `language`, or `pattern` are defined but one doesn’t match, the result is `0` * 3. Matching against `*` gives a score of `5`, matching via equality or via a glob-pattern gives a score of `10` @@ -10812,7 +10877,7 @@ declare module 'vscode' { export function match(selector: DocumentSelector, document: TextDocument): number; /** - * An [event](#Event) which fires when the global set of diagnostics changes. This is + * An {@link Event} which fires when the global set of diagnostics changes. This is * newly added and removed diagnostics. */ export const onDidChangeDiagnostics: Event; @@ -10821,7 +10886,7 @@ declare module 'vscode' { * Get all diagnostics for a given resource. * * @param resource A resource - * @returns An array of [diagnostics](#Diagnostic) objects or an empty array. + * @returns An array of {@link Diagnostic diagnostics} objects or an empty array. */ export function getDiagnostics(resource: Uri): Diagnostic[]; @@ -10835,7 +10900,7 @@ declare module 'vscode' { /** * Create a diagnostics collection. * - * @param name The [name](#DiagnosticCollection.name) of the collection. + * @param name The {@link DiagnosticCollection.name name} of the collection. * @return A new diagnostic collection. */ export function createDiagnosticCollection(name?: string): DiagnosticCollection; @@ -10844,20 +10909,20 @@ declare module 'vscode' { * Register a completion provider. * * Multiple providers can be registered for a language. In that case providers are sorted - * by their [score](#languages.match) and groups of equal score are sequentially asked for + * by their {@link languages.match score} and groups of equal score are sequentially asked for * completion items. The process stops when one or many providers of a group return a * result. A failing provider (rejected promise or exception) will not fail the whole * operation. * * A completion item provider can be associated with a set of `triggerCharacters`. When trigger * characters are being typed, completions are requested but only from providers that registered - * the typed character. Because of that trigger characters should be different than [word characters](#LanguageConfiguration.wordPattern), + * the typed character. Because of that trigger characters should be different than {@link LanguageConfiguration.wordPattern word characters}, * a common trigger character is `.` to trigger member completions. * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A completion provider. * @param triggerCharacters Trigger completion when the user types one of the characters. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerCompletionItemProvider(selector: DocumentSelector, provider: CompletionItemProvider, ...triggerCharacters: string[]): Disposable; @@ -10871,7 +10936,7 @@ declare module 'vscode' { * @param selector A selector that defines the documents this provider is applicable to. * @param provider A code action provider. * @param metadata Metadata about the kind of code actions the provider provides. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerCodeActionsProvider(selector: DocumentSelector, provider: CodeActionProvider, metadata?: CodeActionProviderMetadata): Disposable; @@ -10884,7 +10949,7 @@ declare module 'vscode' { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A code lens provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerCodeLensProvider(selector: DocumentSelector, provider: CodeLensProvider): Disposable; @@ -10897,7 +10962,7 @@ declare module 'vscode' { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A definition provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerDefinitionProvider(selector: DocumentSelector, provider: DefinitionProvider): Disposable; @@ -10910,7 +10975,7 @@ declare module 'vscode' { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider An implementation provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerImplementationProvider(selector: DocumentSelector, provider: ImplementationProvider): Disposable; @@ -10923,7 +10988,7 @@ declare module 'vscode' { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A type definition provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerTypeDefinitionProvider(selector: DocumentSelector, provider: TypeDefinitionProvider): Disposable; @@ -10936,7 +11001,7 @@ declare module 'vscode' { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A declaration provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerDeclarationProvider(selector: DocumentSelector, provider: DeclarationProvider): Disposable; @@ -10949,7 +11014,7 @@ declare module 'vscode' { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A hover provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerHoverProvider(selector: DocumentSelector, provider: HoverProvider): Disposable; @@ -10961,7 +11026,7 @@ declare module 'vscode' { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider An evaluatable expression provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerEvaluatableExpressionProvider(selector: DocumentSelector, provider: EvaluatableExpressionProvider): Disposable; @@ -10976,7 +11041,7 @@ declare module 'vscode' { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider An inline values provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerInlineValuesProvider(selector: DocumentSelector, provider: InlineValuesProvider): Disposable; @@ -10984,12 +11049,12 @@ declare module 'vscode' { * Register a document highlight provider. * * Multiple providers can be registered for a language. In that case providers are sorted - * by their [score](#languages.match) and groups sequentially asked for document highlights. + * by their {@link languages.match score} and groups sequentially asked for document highlights. * The process stops when a provider returns a `non-falsy` or `non-failure` result. * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A document highlight provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerDocumentHighlightProvider(selector: DocumentSelector, provider: DocumentHighlightProvider): Disposable; @@ -11003,7 +11068,7 @@ declare module 'vscode' { * @param selector A selector that defines the documents this provider is applicable to. * @param provider A document symbol provider. * @param metaData metadata about the provider - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerDocumentSymbolProvider(selector: DocumentSelector, provider: DocumentSymbolProvider, metaData?: DocumentSymbolProviderMetadata): Disposable; @@ -11015,7 +11080,7 @@ declare module 'vscode' { * a failure of the whole operation. * * @param provider A workspace symbol provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerWorkspaceSymbolProvider(provider: WorkspaceSymbolProvider): Disposable; @@ -11028,7 +11093,7 @@ declare module 'vscode' { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A reference provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerReferenceProvider(selector: DocumentSelector, provider: ReferenceProvider): Disposable; @@ -11036,12 +11101,12 @@ declare module 'vscode' { * Register a rename provider. * * Multiple providers can be registered for a language. In that case providers are sorted - * by their [score](#languages.match) and asked in sequence. The first provider producing a result + * by their {@link languages.match score} and asked in sequence. The first provider producing a result * defines the result of the whole operation. * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A rename provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerRenameProvider(selector: DocumentSelector, provider: RenameProvider): Disposable; @@ -11049,12 +11114,12 @@ declare module 'vscode' { * Register a semantic tokens provider for a whole document. * * Multiple providers can be registered for a language. In that case providers are sorted - * by their [score](#languages.match) and the best-matching provider is used. Failure + * by their {@link languages.match score} and the best-matching provider is used. Failure * of the selected provider will cause a failure of the whole operation. * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A document semantic tokens provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerDocumentSemanticTokensProvider(selector: DocumentSelector, provider: DocumentSemanticTokensProvider, legend: SemanticTokensLegend): Disposable; @@ -11068,12 +11133,12 @@ declare module 'vscode' { * will be used. * * Multiple providers can be registered for a language. In that case providers are sorted - * by their [score](#languages.match) and the best-matching provider is used. Failure + * by their {@link languages.match score} and the best-matching provider is used. Failure * of the selected provider will cause a failure of the whole operation. * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A document range semantic tokens provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerDocumentRangeSemanticTokensProvider(selector: DocumentSelector, provider: DocumentRangeSemanticTokensProvider, legend: SemanticTokensLegend): Disposable; @@ -11081,29 +11146,29 @@ declare module 'vscode' { * Register a formatting provider for a document. * * Multiple providers can be registered for a language. In that case providers are sorted - * by their [score](#languages.match) and the best-matching provider is used. Failure + * by their {@link languages.match score} and the best-matching provider is used. Failure * of the selected provider will cause a failure of the whole operation. * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A document formatting edit provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerDocumentFormattingEditProvider(selector: DocumentSelector, provider: DocumentFormattingEditProvider): Disposable; /** * Register a formatting provider for a document range. * - * *Note:* A document range provider is also a [document formatter](#DocumentFormattingEditProvider) - * which means there is no need to [register](#languages.registerDocumentFormattingEditProvider) a document + * *Note:* A document range provider is also a {@link DocumentFormattingEditProvider document formatter} + * which means there is no need to {@link languages.registerDocumentFormattingEditProvider register} a document * formatter when also registering a range provider. * * Multiple providers can be registered for a language. In that case providers are sorted - * by their [score](#languages.match) and the best-matching provider is used. Failure + * by their {@link languages.match score} and the best-matching provider is used. Failure * of the selected provider will cause a failure of the whole operation. * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A document range formatting edit provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerDocumentRangeFormattingEditProvider(selector: DocumentSelector, provider: DocumentRangeFormattingEditProvider): Disposable; @@ -11111,14 +11176,14 @@ declare module 'vscode' { * Register a formatting provider that works on type. The provider is active when the user enables the setting `editor.formatOnType`. * * Multiple providers can be registered for a language. In that case providers are sorted - * by their [score](#languages.match) and the best-matching provider is used. Failure + * by their {@link languages.match score} and the best-matching provider is used. Failure * of the selected provider will cause a failure of the whole operation. * * @param selector A selector that defines the documents this provider is applicable to. * @param provider An on type formatting edit provider. * @param firstTriggerCharacter A character on which formatting should be triggered, like `}`. * @param moreTriggerCharacter More trigger characters. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerOnTypeFormattingEditProvider(selector: DocumentSelector, provider: OnTypeFormattingEditProvider, firstTriggerCharacter: string, ...moreTriggerCharacter: string[]): Disposable; @@ -11126,14 +11191,14 @@ declare module 'vscode' { * Register a signature help provider. * * Multiple providers can be registered for a language. In that case providers are sorted - * by their [score](#languages.match) and called sequentially until a provider returns a + * by their {@link languages.match score} and called sequentially until a provider returns a * valid result. * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A signature help provider. * @param triggerCharacters Trigger signature help when the user types one of the characters, like `,` or `(`. * @param metadata Information about the provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerSignatureHelpProvider(selector: DocumentSelector, provider: SignatureHelpProvider, ...triggerCharacters: string[]): Disposable; export function registerSignatureHelpProvider(selector: DocumentSelector, provider: SignatureHelpProvider, metadata: SignatureHelpProviderMetadata): Disposable; @@ -11147,7 +11212,7 @@ declare module 'vscode' { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A document link provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerDocumentLinkProvider(selector: DocumentSelector, provider: DocumentLinkProvider): Disposable; @@ -11160,7 +11225,7 @@ declare module 'vscode' { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A color provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerColorProvider(selector: DocumentSelector, provider: DocumentColorProvider): Disposable; @@ -11177,7 +11242,7 @@ declare module 'vscode' { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A folding range provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerFoldingRangeProvider(selector: DocumentSelector, provider: FoldingRangeProvider): Disposable; @@ -11190,7 +11255,7 @@ declare module 'vscode' { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A selection range provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerSelectionRangeProvider(selector: DocumentSelector, provider: SelectionRangeProvider): Disposable; @@ -11199,7 +11264,7 @@ declare module 'vscode' { * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A call hierarchy provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerCallHierarchyProvider(selector: DocumentSelector, provider: CallHierarchyProvider): Disposable; @@ -11207,343 +11272,1339 @@ declare module 'vscode' { * Register a linked editing range provider. * * Multiple providers can be registered for a language. In that case providers are sorted - * by their [score](#languages.match) and the best-matching provider that has a result is used. Failure + * by their {@link languages.match score} and the best-matching provider that has a result is used. Failure * of the selected provider will cause a failure of the whole operation. * * @param selector A selector that defines the documents this provider is applicable to. * @param provider A linked editing range provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerLinkedEditingRangeProvider(selector: DocumentSelector, provider: LinkedEditingRangeProvider): Disposable; /** - * Set a [language configuration](#LanguageConfiguration) for a language. + * Set a {@link LanguageConfiguration language configuration} for a language. * * @param language A language identifier like `typescript`. * @param configuration Language configuration. - * @return A [disposable](#Disposable) that unsets this configuration. + * @return A {@link Disposable} that unsets this configuration. */ export function setLanguageConfiguration(language: string, configuration: LanguageConfiguration): Disposable; } /** - * Represents the input box in the Source Control viewlet. + * A notebook cell kind. */ - export interface SourceControlInputBox { + export enum NotebookCellKind { /** - * Setter and getter for the contents of the input box. + * A markup-cell is formatted source that is used for display. */ - value: string; + Markup = 1, /** - * A string to show as placeholder in the input box to guide the user. + * A code-cell is source that can be {@link NotebookController executed} and that + * produces {@link NotebookCellOutput output}. */ - placeholder: string; + Code = 2 + } + + /** + * Represents a cell of a {@link NotebookDocument notebook}, either a {@link NotebookCellKind.Code code}-cell + * or {@link NotebookCellKind.Markup markup}-cell. + * + * NotebookCell instances are immutable and are kept in sync for as long as they are part of their notebook. + */ + export interface NotebookCell { /** - * Controls whether the input box is visible (default is `true`). + * The index of this cell in its {@link NotebookDocument.cellAt containing notebook}. The + * index is updated when a cell is moved within its notebook. The index is `-1` + * when the cell has been removed from its notebook. */ - visible: boolean; - } + readonly index: number; - interface QuickDiffProvider { + /** + * The {@link NotebookDocument notebook} that contains this cell. + */ + readonly notebook: NotebookDocument; /** - * Provide a [uri](#Uri) to the original resource of any given resource uri. - * - * @param uri The uri of the resource open in a text editor. - * @param token A cancellation token. - * @return A thenable that resolves to uri of the matching original resource. + * The kind of this cell. */ - provideOriginalResource?(uri: Uri, token: CancellationToken): ProviderResult; - } + readonly kind: NotebookCellKind; - /** - * The theme-aware decorations for a - * [source control resource state](#SourceControlResourceState). - */ - export interface SourceControlResourceThemableDecorations { + /** + * The {@link TextDocument text} of this cell, represented as text document. + */ + readonly document: TextDocument; /** - * The icon path for a specific - * [source control resource state](#SourceControlResourceState). + * The metadata of this cell. */ - readonly iconPath?: string | Uri; + readonly metadata: NotebookCellMetadata + + /** + * The outputs of this cell. + */ + readonly outputs: readonly NotebookCellOutput[]; + + /** + * The most recent {@link NotebookCellExecutionSummary excution summary} for this cell. + */ + readonly executionSummary?: NotebookCellExecutionSummary; } /** - * The decorations for a [source control resource state](#SourceControlResourceState). - * Can be independently specified for light and dark themes. + * Represents a notebook which itself is a sequence of {@link NotebookCell code or markup cells}. Notebook documents are + * created from {@link NotebookData notebook data}. */ - export interface SourceControlResourceDecorations extends SourceControlResourceThemableDecorations { + export interface NotebookDocument { /** - * Whether the [source control resource state](#SourceControlResourceState) should - * be striked-through in the UI. + * The associated uri for this notebook. + * + * *Note* that most notebooks use the `file`-scheme, which means they are files on disk. However, **not** all notebooks are + * saved on disk and therefore the `scheme` must be checked before trying to access the underlying file or siblings on disk. + * + * @see {@link FileSystemProvider} */ - readonly strikeThrough?: boolean; + readonly uri: Uri; + + /** @deprecated */ + // todo@API remove + readonly viewType: string; /** - * Whether the [source control resource state](#SourceControlResourceState) should - * be faded in the UI. + * The type of notebook. */ - readonly faded?: boolean; + readonly notebookType: string; /** - * The title for a specific - * [source control resource state](#SourceControlResourceState). + * The version number of this notebook (it will strictly increase after each + * change, including undo/redo). */ - readonly tooltip?: string; + readonly version: number; /** - * The light theme decorations. + * `true` if there are unpersisted changes. */ - readonly light?: SourceControlResourceThemableDecorations; + readonly isDirty: boolean; /** - * The dark theme decorations. + * Is this notebook representing an untitled file which has not been saved yet. */ - readonly dark?: SourceControlResourceThemableDecorations; - } + readonly isUntitled: boolean; - /** - * An source control resource state represents the state of an underlying workspace - * resource within a certain [source control group](#SourceControlResourceGroup). - */ - export interface SourceControlResourceState { + /** + * `true` if the notebook has been closed. A closed notebook isn't synchronized anymore + * and won't be re-used when the same resource is opened again. + */ + readonly isClosed: boolean; /** - * The [uri](#Uri) of the underlying resource inside the workspace. + * The {@link NotebookDocumentMetadata metadata} for this notebook. */ - readonly resourceUri: Uri; + readonly metadata: NotebookDocumentMetadata; /** - * The [command](#Command) which should be run when the resource - * state is open in the Source Control viewlet. + * The number of cells in the notebook. */ - readonly command?: Command; + readonly cellCount: number; /** - * The [decorations](#SourceControlResourceDecorations) for this source control - * resource state. + * Return the cell at the specified index. The index will be adjusted to the notebook. + * + * @param index - The index of the cell to retrieve. + * @return A {@link NotebookCell cell}. */ - readonly decorations?: SourceControlResourceDecorations; + cellAt(index: number): NotebookCell; /** - * Context value of the resource state. This can be used to contribute resource specific actions. - * For example, if a resource is given a context value as `diffable`. When contributing actions to `scm/resourceState/context` - * using `menus` extension point, you can specify context value for key `scmResourceState` in `when` expressions, like `scmResourceState == diffable`. - * ``` - * "contributes": { - * "menus": { - * "scm/resourceState/context": [ - * { - * "command": "extension.diff", - * "when": "scmResourceState == diffable" - * } - * ] - * } - * } - * ``` - * This will show action `extension.diff` only for resources with `contextValue` is `diffable`. + * Get the cells of this notebook. A subset can be retrieved by providing + * a range. The range will be adjuset to the notebook. + * + * @param range A notebook range. + * @returns The cells contained by the range or all cells. */ - readonly contextValue?: string; + getCells(range?: NotebookRange): NotebookCell[]; + + /** + * Save the document. The saving will be handled by the corresponding {@link NotebookSerializer serializer}. + * + * @return A promise that will resolve to true when the document + * has been saved. Will return false if the file was not dirty or when save failed. + */ + save(): Thenable; } - /** - * A source control resource group is a collection of - * [source control resource states](#SourceControlResourceState). - */ - export interface SourceControlResourceGroup { + // todo@API jsdoc + export class NotebookCellMetadata { /** - * The id of this source control resource group. + * Whether a code cell's editor is collapsed */ - readonly id: string; + // todo@API decouple from metadata? extract as dedicated field or inside an options object and leave metadata purely for extensions? + readonly inputCollapsed?: boolean; /** - * The label of this source control resource group. + * Whether a code cell's outputs are collapsed */ - label: string; + // todo@API decouple from metadata? extract as dedicated field or inside an options object and leave metadata purely for extensions? + readonly outputCollapsed?: boolean; /** - * Whether this source control resource group is hidden when it contains - * no [source control resource states](#SourceControlResourceState). + * Additional attributes of a cell metadata. */ - hideWhenEmpty?: boolean; + readonly [key: string]: any; /** - * This group's collection of - * [source control resource states](#SourceControlResourceState). + * Create a new notebook cell metadata. + * + * @param inputCollapsed Whether a code cell's editor is collapsed + * @param outputCollapsed Whether a code cell's outputs are collapsed */ - resourceStates: SourceControlResourceState[]; + constructor(inputCollapsed?: boolean, outputCollapsed?: boolean); /** - * Dispose this source control resource group. + * Derived a new cell metadata from this metadata. + * + * @param change An object that describes a change to this NotebookCellMetadata. + * @return A new NotebookCellMetadata that reflects the given change. Will return `this` NotebookCellMetadata if the change + * is not changing anything. */ - dispose(): void; + with(change: { inputCollapsed?: boolean | null, outputCollapsed?: boolean | null, [key: string]: any }): NotebookCellMetadata; } /** - * An source control is able to provide [resource states](#SourceControlResourceState) - * to the editor and interact with the editor in several source control related ways. + * The summary of a notebook cell execution. */ - export interface SourceControl { + export interface NotebookCellExecutionSummary { /** - * The id of this source control. + * The order in which the execution happened. */ - readonly id: string; + readonly executionOrder?: number; /** - * The human-readable label of this source control. + * If the exclusive finished successfully. */ - readonly label: string; + readonly success?: boolean; /** - * The (optional) Uri of the root of this source control. + * The unix timestamp at which execution started. */ - readonly rootUri: Uri | undefined; + // todo@API use duration instead of start/end? + readonly startTime?: number; /** - * The [input box](#SourceControlInputBox) for this source control. + * The unix timestamp at which execution ended. */ - readonly inputBox: SourceControlInputBox; + readonly endTime?: number; + } + // todo@API jsdoc + // todo@API remove this and use simple {}? + export class NotebookDocumentMetadata { /** - * The UI-visible count of [resource states](#SourceControlResourceState) of - * this source control. - * - * Equals to the total number of [resource state](#SourceControlResourceState) - * of this source control, if undefined. + * Additional attributes of the document metadata. */ - count?: number; + readonly [key: string]: any; /** - * An optional [quick diff provider](#QuickDiffProvider). + * Create a new notebook document metadata */ - quickDiffProvider?: QuickDiffProvider; + constructor(); /** - * Optional commit template string. + * Derived a new document metadata from this metadata. * - * The Source Control viewlet will populate the Source Control - * input with this value when appropriate. + * @param change An object that describes a change to this NotebookDocumentMetadata. + * @return A new NotebookDocumentMetadata that reflects the given change. Will return `this` NotebookDocumentMetadata if the change + * is not changing anything. */ - commitTemplate?: string; + with(change: { [key: string]: any }): NotebookDocumentMetadata + } - /** - * Optional accept input command. - * - * This command will be invoked when the user accepts the value - * in the Source Control input. - */ - acceptInputCommand?: Command; + /** + * A notebook range represents an ordered pair of two cell indicies. + * It is guaranteed that start is less than or equal to end. + */ + export class NotebookRange { /** - * Optional status bar commands. - * - * These commands will be displayed in the editor's status bar. + * The zero-based start index of this range. */ - statusBarCommands?: Command[]; + readonly start: number; /** - * Create a new [resource group](#SourceControlResourceGroup). + * The exclusive end index of this range (zero-based). */ - createResourceGroup(id: string, label: string): SourceControlResourceGroup; + readonly end: number; /** - * Dispose this source control. + * `true` if `start` and `end` are equal. */ - dispose(): void; - } - - export namespace scm { + readonly isEmpty: boolean; /** - * The [input box](#SourceControlInputBox) for the last source control - * created by the extension. + * Create a new notebook range. If `start` is not + * before or equal to `end`, the values will be swapped. * - * @deprecated Use SourceControl.inputBox instead + * @param start start index + * @param end end index. */ - export const inputBox: SourceControlInputBox; + constructor(start: number, end: number); /** - * Creates a new [source control](#SourceControl) instance. + * Derive a new range for this range. * - * @param id An `id` for the source control. Something short, e.g.: `git`. - * @param label A human-readable string for the source control. E.g.: `Git`. - * @param rootUri An optional Uri of the root of the source control. E.g.: `Uri.parse(workspaceRoot)`. - * @return An instance of [source control](#SourceControl). + * @param change An object that describes a change to this range. + * @return A range that reflects the given change. Will return `this` range if the change + * is not changing anything. */ - export function createSourceControl(id: string, label: string, rootUri?: Uri): SourceControl; - } - - /** - * A DebugProtocolMessage is an opaque stand-in type for the [ProtocolMessage](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_ProtocolMessage) type defined in the Debug Adapter Protocol. - */ - export interface DebugProtocolMessage { - // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_ProtocolMessage). + with(change: { start?: number, end?: number }): NotebookRange; } /** - * A DebugProtocolSource is an opaque stand-in type for the [Source](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Source) type defined in the Debug Adapter Protocol. + * One representation of a {@link NotebookCellOutput notebook output}, defined by MIME type and data. */ - export interface DebugProtocolSource { - // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Source). - } + export class NotebookCellOutputItem { - /** - * A DebugProtocolBreakpoint is an opaque stand-in type for the [Breakpoint](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Breakpoint) type defined in the Debug Adapter Protocol. - */ - export interface DebugProtocolBreakpoint { - // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Breakpoint). - } + /** + * Factory function to create a `NotebookCellOutputItem` from a string. + * + * *Note* that an UTF-8 encoder is used to create bytes for the string. + * + * @param value A string. + * @param mime Optional MIME type, defaults to `text/plain`. + * @param metadata Optional metadata. + * @returns A new output item object. + */ + static text(value: string, mime?: string, metadata?: { [key: string]: any }): NotebookCellOutputItem; - /** - * Configuration for a debug session. - */ - export interface DebugConfiguration { /** - * The type of the debug session. + * Factory function to create a `NotebookCellOutputItem` from + * a JSON object. + * + * *Note* that this function is not expecting "stringified JSON" but + * an object that can be stringified. This function will throw an error + * when the passed value cannot be JSON-stringified. + * + * @param value A JSON-stringifyable value. + * @param mime Optional MIME type, defaults to `application/json` + * @param metadata Optional metadata. + * @returns A new output item object. */ - type: string; + static json(value: any, mime?: string, metadata?: { [key: string]: any }): NotebookCellOutputItem; /** - * The name of the debug session. + * Factory function to create a `NotebookCellOutputItem` that uses + * uses the `application/vnd.code.notebook.stdout` mime type. + * + * @param value A string. + * @param metadata Optional metadata. + * @returns A new output item object. */ - name: string; + static stdout(value: string, metadata?: { [key: string]: any }): NotebookCellOutputItem; /** - * The request type of the debug session. + * Factory function to create a `NotebookCellOutputItem` that uses + * uses the `application/vnd.code.notebook.stderr` mime type. + * + * @param value A string. + * @param metadata Optional metadata. + * @returns A new output item object. */ - request: string; + static stderr(value: string, metadata?: { [key: string]: any }): NotebookCellOutputItem; /** - * Additional debug type specific properties. + * Factory function to create a `NotebookCellOutputItem` that uses + * uses the `application/vnd.code.notebook.error` mime type. + * + * @param value An error object. + * @param metadata Optional metadata. + * @returns A new output item object. */ - [key: string]: any; - } + static error(value: Error, metadata?: { [key: string]: any }): NotebookCellOutputItem; - /** - * A debug session. - */ - export interface DebugSession { + /** + * The mime type which determines how the {@link NotebookCellOutputItem.value `value`}-property + * is interpreted. + * + * Notebooks have built-in support for certain mime-types, extensions can add support for new + * types and override existing types. + */ + mime: string; /** - * The unique ID of this debug session. + * The data of this output item. Must always be an array of unsigned 8-bit integers. */ - readonly id: string; + data: Uint8Array; + + //todo@API remove in favour of NotebookCellOutput#metadata + metadata?: { [key: string]: any }; /** - * The debug session's type from the [debug configuration](#DebugConfiguration). + * Create a new notbook cell output item. + * + * @param data The value of the output item. + * @param mime The mime type of the output item. + * @param metadata Optional metadata for this output item. + */ + constructor(data: Uint8Array, mime: string, metadata?: { [key: string]: any }); + } + + /** + * Notebook cell output represents a result of executing a cell. It is a container type for multiple + * {@link NotebookCellOutputItem output items} where contained items represent the same result but + * use different MIME types. + */ + //todo@API - add sugar function to add more outputs + export class NotebookCellOutput { + + /** + * Identifier for this output. Using the identifier allows a subsequent execution to modify + * existing output. Defaults to a fresh UUID. + */ + id: string; + + /** + * The output items of this output. Each item must represent the same result. _Note_ that repeated + * MIME types per output is invalid and that the editor will just pick one of them. + * + * ```ts + * new vscode.NotebookCellOutput([ + * vscode.NotebookCellOutputItem.text('Hello', 'text/plain'), + * vscode.NotebookCellOutputItem.text('Hello', 'text/html'), + * vscode.NotebookCellOutputItem.text('_Hello_', 'text/markdown'), + * vscode.NotebookCellOutputItem.text('Hey', 'text/plain'), // INVALID: repeated type, editor will pick just one + * ]) + * ``` + */ + items: NotebookCellOutputItem[]; + + /** + * Arbitrary metadata for this cell output. Must be JSON-stringifyable. + */ + //todo@API have this OR NotebookCellOutputItem#metadata but not both? Preference for this. + metadata?: { [key: string]: any }; + + /** + * Create new notebook output. + * + * @param outputs Notebook output items. + * @param metadata Optional metadata. + */ + constructor(outputs: NotebookCellOutputItem[], metadata?: { [key: string]: any }); + + /** + * Create new notebook output. + * + * @param items Notebook output items. + * @param id Identifier of this output. + * @param metadata Optional metadata. + */ + //todo@API id-args is not used by jupyter but we it added with display_id in mind... + constructor(items: NotebookCellOutputItem[], id: string, metadata?: { [key: string]: any }); + } + + /** + * NotebookCellData is the raw representation of notebook cells. Its is part of {@link NotebookData `NotebookData`}. + */ + export class NotebookCellData { + + /** + * The {@link NotebookCellKind kind} of this cell data. + */ + kind: NotebookCellKind; + + /** + * The source value of this cell data - either source code or formatted text. + */ + value: string; + + /** + * The language identifier of the source value of this cell data. Any value from + * {@link languages.getLanguages `getLanguages`} is possible. + */ + languageId: string; + + /** + * The outputs of this cell data. + */ + outputs?: NotebookCellOutput[]; + + /** + * The metadata of this cell data. + */ + metadata?: NotebookCellMetadata; + + /** + * The execution summary of this cell data. + */ + executionSummary?: NotebookCellExecutionSummary; + + /** + * Create new cell data. Minimal cell data specifies its kind, its source value, and the + * language identifier of its source. + * + * @param kind The kind. + * @param value The source value. + * @param languageId The language identifier of the source value. + * @param outputs Optional outputs. + * @param metadata Optional metadata. + * @param executionSummary Optional execution summary. + */ + // todo@API should ctors only have the args for required properties? + constructor(kind: NotebookCellKind, value: string, languageId: string, outputs?: NotebookCellOutput[], metadata?: NotebookCellMetadata, executionSummary?: NotebookCellExecutionSummary); + } + + /** + * NotebookData is the raw representation of notebooks. + * + * Extensions are responsible to create {@link NotebookData `NotebookData`} so that the editor + * can create a {@link NotebookDocument `NotebookDocument`}. + * + * @see {@link NotebookSerializer} + */ + export class NotebookData { + /** + * The cell data of this notebook data. + */ + cells: NotebookCellData[]; + + /** + * The metadata of this notebook data. + */ + metadata: NotebookDocumentMetadata; + + /** + * Create new notebook data. + * + * @param cells An array of cell data. + * @param metadata Notebook metadata. + */ + constructor(cells: NotebookCellData[], metadata?: NotebookDocumentMetadata); + } + + /** + * The notebook serializer enables the editor to open notebook files. + * + * At its core the editor only knows a {@link NotebookData notebook data structure} but not + * how that data structure is written to a file, nor how it is read from a file. The + * notebook serializer bridges this gap by deserializing bytes into notebook data and + * vice versa. + */ + export interface NotebookSerializer { + + /** + * Deserialize contents of a notebook file into the notebook data structure. + * + * @param content Contents of a notebook file. + * @param token A cancellation token. + * @return Notebook data or a thenable that resolves to such. + */ + deserializeNotebook(content: Uint8Array, token: CancellationToken): NotebookData | Thenable; + + /** + * Serialize notebook data into file contents. + * + * @param data A notebook data structure. + * @param token A cancellation token. + * @returns An array of bytes or a thenable that resolves to such. + */ + serializeNotebook(data: NotebookData, token: CancellationToken): Uint8Array | Thenable; + } + + /** + * Notebook content options define what parts of a notebook are persisted. Note + * + * For instance, a notebook serializer can opt-out of saving outputs and in that case the editor doesn't mark a + * notebooks as {@link NotebookDocument.isDirty dirty} when its output has changed. + */ + export interface NotebookDocumentContentOptions { + /** + * Controls if outputs change will trigger notebook document content change and if it will be used in the diff editor + * Default to false. If the content provider doesn't persisit the outputs in the file document, this should be set to true. + */ + transientOutputs?: boolean; + + /** + * Controls if a cell metadata property change will trigger notebook document content change and if it will be used in the diff editor + * Default to false. If the content provider doesn't persisit a metadata property in the file document, it should be set to true. + */ + transientCellMetadata?: { [K in keyof NotebookCellMetadata]?: boolean }; + + /** + * Controls if a document metadata property change will trigger notebook document content change and if it will be used in the diff editor + * Default to false. If the content provider doesn't persisit a metadata property in the file document, it should be set to true. + */ + // todo@API ...NotebookDocument... or just ...Notebook... just like...Cell... above + transientDocumentMetadata?: { [K in keyof NotebookDocumentMetadata]?: boolean }; + } + + /** + * A callback that is invoked by the editor whenever cell execution has been triggered. + */ + //todo@API inline? + export interface NotebookExecuteHandler { + /** + * @param cells The notebook cells to execute. + * @param notebook The notebook for which the execute handler is being called. + * @param controller The controller that the handler is attached to + */ + (this: NotebookController, cells: NotebookCell[], notebook: NotebookDocument, controller: NotebookController): void | Thenable + } + + /** + * Notebook controller affinity for notebook documents. + * + * @see {@link NotebookController.updateNotebookAffinity} + */ + export enum NotebookControllerAffinity { + /** + * Default affinity. + */ + Default = 1, + /** + * A controller is preferred for a notebook. + */ + Preferred = 2 + } + + /** + * A notebook controller represents an entity that can execute notebook cells. This is often referred to as a kernel. + * + * There can be multiple controllers and the editor will let users choose which controller to use for a certain notebook. The + * {@link NotebookController.notebookType `notebookType`}-property defines for what kind of notebooks a controller is for and + * the {@link NotebookController.updateNotebookAffinity `updateNotebookAffinity`}-function allows controllers to set a preference + * for specific notebook documents. + * + * When a cell is being run the editor will invoke the {@link NotebookController.executeHandler `executeHandler`} and a controller + * is expected to create and finalize a {@link NotebookCellExecution notebook cell execution}. However, controllers are also free + * to create executions by themselves. + */ + export interface NotebookController { + + /** + * The identifier of this notebook controller. + * + * _Note_ that controllers are remembered by their identifier and that extensions should use + * stable identifiers across sessions. + */ + readonly id: string; + + // todo@api remove + /** @deprecated */ + readonly viewType: string; + + /** + * The notebook type this controller is for. + */ + readonly notebookType: string; + + /** + * An array of language identifiers that are supported by this + * controller. Any language identifier from {@link languages.getLanguages `getLanguages`} + * is possible. When falsy all languages are supported. + * + * Samples: + * ```js + * // support JavaScript and TypeScript + * myController.supportedLanguages = ['javascript', 'typescript'] + * + * // support all languages + * myController.supportedLanguages = undefined; // falsy + * myController.supportedLanguages = []; // falsy + * ``` + */ + supportedLanguages?: string[]; + + /** + * The human-readable label of this notebook controller. + */ + label: string; + + /** + * The human-readable description which is rendered less prominent. + */ + description?: string; + + /** + * The human-readable detail which is rendered less prominent. + */ + detail?: string; + + /** + * Whether this controller supports execution order so that the + * editor can render placeholders for them. + */ + supportsExecutionOrder?: boolean; + + // todo@API remove + /** @deprecated */ + hasExecutionOrder?: boolean; + + /** + * Create a cell execution task. + * + * _Note_ that there can only be one execution per cell at a time and that an error is thrown if + * a cell execution is created while another is still active. + * + * This should be used in response to the {@link NotebookController.executeHandler execution handler} + * being called or when cell execution has been started else, e.g when a cell was already + * executing or when cell execution was triggered from another source. + * + * @param cell The notebook cell for which to create the execution. + * @returns A notebook cell execution. + */ + createNotebookCellExecution(cell: NotebookCell): NotebookCellExecution; + + /** + * The execute handler is invoked when the run gestures in the UI are selected, e.g Run Cell, Run All, + * Run Selection etc. The execute handler is responsible for creating and managing {@link NotebookCellExecution execution}-objects. + */ + executeHandler: NotebookExecuteHandler; + + /** + * Optional interrupt handler. + * + * By default cell execution is canceled via {@link NotebookCellExecution.token tokens}. Cancellation + * tokens require that a controller can keep track of its execution so that it can cancel a specific execution at a later + * point. Not all scenarios allow for that, eg. REPL-style controllers often work by interrupting whatever is currently + * running. For those cases the interrupt handler exists - it can be thought of as the equivalent of `SIGINT` + * or `Control+C` in terminals. + * + * _Note_ that supporting {@link NotebookCellExecution.token cancellation tokens} is preferred and that interrupt handlers should + * only be used when tokens cannot be supported. + */ + interruptHandler?: (this: NotebookController, notebook: NotebookDocument) => void | Thenable; + + /** + * An event that fires whenever a controller has been selected for a notebook document. Selecting a controller + * for a notebook is a user gesture and happens either explicitly or implicitly when interacting while a + * controller was suggested. + */ + //todo@api rename to ...NotebookDocument... + readonly onDidChangeNotebookAssociation: Event<{ notebook: NotebookDocument, selected: boolean }>; + + /** + * A controller can set affinities for specific notebook documents. This allows a controller + * to be presented more prominent for some notebooks. + * + * @param notebook The notebook for which a priority is set. + * @param affinity A controller affinity + */ + updateNotebookAffinity(notebook: NotebookDocument, affinity: NotebookControllerAffinity): void; + + /** + * Dispose and free associated resources. + */ + dispose(): void; + } + + // todo@api jsdoc + // todo@api Inline unless we can come up with more (future) properties + export interface NotebookCellExecuteStartContext { + /** + * The time that execution began, in milliseconds in the Unix epoch. Used to drive the clock + * that shows for how long a cell has been running. If not given, the clock won't be shown. + */ + startTime?: number; + } + + // todo@api jsdoc + // todo@api Inline unless we can come up with more (future) properties + export interface NotebookCellExecuteEndContext { + /** + * If true, a green check is shown on the cell status bar. + * If false, a red X is shown. + * If undefined, no check or X icon is shown. + */ + success?: boolean; + + /** + * The time that execution finished, in milliseconds in the Unix epoch. + */ + endTime?: number; + } + + /** + * A NotebookCellExecution is how {@link NotebookController notebook controller} modify a notebook cell as + * it is executing. + * + * When a cell execution object is created, the cell enters the {@link NotebookCellExecutionState.Pending `Pending`} state. + * When {@link NotebookCellExecution.start `start(...)`} is called on the execution task, it enters the {@link NotebookCellExecutionState.Executing `Executing`} state. When + * {@link NotebookCellExecution.end `end(...)`} is called, it enters the {@link NotebookCellExecutionState.Idle `Idle`} state. + */ + export interface NotebookCellExecution { + + /** + * The {@link NotebookCell cell} for which this execution has been created. + */ + readonly cell: NotebookCell; + + /** + * A cancellation token which will be triggered when the cell execution is canceled + * from the UI. + * + * _Note_ that the cancellation token will not be triggered when the {@link NotebookController controller} + * that created this execution uses an {@link NotebookController.interruptHandler interrupt-handler}. + */ + readonly token: CancellationToken; + + /** + * Set and unset the order of this cell execution. + */ + executionOrder: number | undefined; + + // todo@API inline context object? + start(context?: NotebookCellExecuteStartContext): void; + + // todo@API inline context object? + end(result?: NotebookCellExecuteEndContext): void; + + /** + * Clears the output of the cell that is executing or of another cell that is affected by this execution. + * + * @param cell Cell for which output is cleared. Defaults to the {@link NotebookCellExecution.cell cell} of + * this execution. + * @return A thenable that resolves when the operation finished. + */ + clearOutput(cell?: NotebookCell): Thenable; + + /** + * Replace the output of the cell that is executing or of another cell that is affected by this execution. + * + * @param out Output that replaces the current output. + * @param cell Cell for which output is cleared. Defaults to the {@link NotebookCellExecution.cell cell} of + * this execution. + * @return A thenable that resolves when the operation finished. + */ + replaceOutput(out: NotebookCellOutput | NotebookCellOutput[], cell?: NotebookCell): Thenable; + + /** + * Append to the output of the cell that is executing or to another cell that is affected by this execution. + * + * @param out Output that is appended to the current output. + * @param cell Cell for which output is cleared. Defaults to the {@link NotebookCellExecution.cell cell} of + * this execution. + * @return A thenable that resolves when the operation finished. + */ + appendOutput(out: NotebookCellOutput | NotebookCellOutput[], cell?: NotebookCell): Thenable; + + /** + * Replace all output items of existing cell output. + * + * @param items Output items that replace the items of existing output. + * @param output Output object or the identifier of one. + * @return A thenable that resolves when the operation finished. + */ + replaceOutputItems(items: NotebookCellOutputItem | NotebookCellOutputItem[], output: NotebookCellOutput | string): Thenable; + + /** + * Append output items to existing cell output. + * + * @param items Output items that are append to existing output. + * @param output Output object or the identifier of one. + * @return A thenable that resolves when the operation finished. + */ + appendOutputItems(items: NotebookCellOutputItem | NotebookCellOutputItem[], output: NotebookCellOutput | string): Thenable; + } + + /** + * Represents the alignment of status bar items. + */ + export enum NotebookCellStatusBarAlignment { + + /** + * Aligned to the left side. + */ + Left = 1, + + /** + * Aligned to the right side. + */ + Right = 2 + } + + /** + * A contribution to a cell's status bar + */ + export class NotebookCellStatusBarItem { + /** + * The text to show for the item. + */ + text: string; + + /** + * Whether the item is aligned to the left or right. + */ + alignment: NotebookCellStatusBarAlignment; + + /** + * An optional command to execute when the item is clicked. + */ + //todo@API only have Command? + command?: string | Command; + + /** + * A tooltip to show when the item is hovered. + */ + tooltip?: string; + + /** + * The priority of the item. A higher value item will be shown more to the left. + */ + priority?: number; + + /** + * Accessibility information used when a screen reader interacts with this item. + */ + accessibilityInformation?: AccessibilityInformation; + + /** + * Creates a new NotebookCellStatusBarItem. + */ + // todo@API jsdoc for args + // todo@API should ctors only have the args for required properties? + constructor(text: string, alignment: NotebookCellStatusBarAlignment, command?: string | Command, tooltip?: string, priority?: number, accessibilityInformation?: AccessibilityInformation); + } + + /** + * A provider that can contribute items to the status bar that appears below a cell's editor. + */ + export interface NotebookCellStatusBarItemProvider { + /** + * An optional event to signal that statusbar items have changed. The provide method will be called again. + */ + onDidChangeCellStatusBarItems?: Event; + + /** + * The provider will be called when the cell scrolls into view, when its content, outputs, language, or metadata change, and when it changes execution state. + * @param cell The cell for which to return items. + * @param token A token triggered if this request should be cancelled. + */ + //todo@API jsdoc for return-type + //todo@API should this return an item instead of an array? + provideCellStatusBarItems(cell: NotebookCell, token: CancellationToken): ProviderResult; + } + + /** + * Namespace for notebooks. + * + * The notebooks functionality is composed of three loosly coupled components: + * + * 1. {@link NotebookSerializer} enable the editor to open, show, and save notebooks + * 2. {@link NotebookController} own the execution of notebooks, e.g they create output from code cells. + * 3. NotebookRenderer present notebook output in the editor. They run in a separate context. + */ + // todo@api what should be in this namespace? should notebookDocuments and friends be in the workspace namespace? + export namespace notebooks { + + /** + * All notebook documents currently known to the editor. + */ + export const notebookDocuments: readonly NotebookDocument[]; + + /** + * Open a notebook. Will return early if this notebook is already {@link notebook.notebookDocuments loaded}. Otherwise + * the notebook is loaded and the {@link notebook.onDidOpenNotebookDocument `onDidOpenNotebookDocument`}-event fires. + * + * *Note* that the lifecycle of the returned notebook is owned by the editor and not by the extension. That means an + * {@link notebook.onDidCloseNotebookDocument `onDidCloseNotebookDocument`}-event can occur at any time after. + * + * *Note* that opening a notebook does not show a notebook editor. This function only returns a notebook document which + * can be showns in a notebook editor but it can also be used for other things. + * + * @param uri The resource to open. + * @returns A promise that resolves to a {@link NotebookDocument notebook} + */ + export function openNotebookDocument(uri: Uri): Thenable; + + /** + * Open an untitled notebook. The editor will prompt the user for a file + * path when the document is to be saved. + * + * @see {@link openNotebookDocument} + * @param notebookType The notebook type that should be used. + * @param content The initial contents of the notebook. + * @returns A promise that resolves to a {@link NotebookDocument notebook}. + */ + export function openNotebookDocument(notebookType: string, content?: NotebookData): Thenable; + + /** + * An event that is emitted when a {@link NotebookDocument notebook} is opened. + */ + export const onDidOpenNotebookDocument: Event; + + /** + * An event that is emitted when a {@link NotebookDocument notebook} is disposed. + * + * *Note 1:* There is no guarantee that this event fires when an editor tab is closed. + * + * *Note 2:* A notebook can be open but not shown in an editor which means this event can fire + * for a notebook that has not been shown in an editor. + */ + export const onDidCloseNotebookDocument: Event; + + /** + * Register a {@link NotebookSerializer notebook serializer}. + * + * A notebook serializer must to be contributed through the `notebooks` extension point. When opening a notebook file, the editor will send + * the `onNotebook:` activation event, and extensions must register their serializer in return. + * + * @param notebookType A notebook. + * @param serializer A notebook serialzier. + * @param options Optional context options that define what parts of a notebook should be persisted + * @return A {@link Disposable} that unregisters this serializer when being disposed. + */ + export function registerNotebookSerializer(notebookType: string, serializer: NotebookSerializer, options?: NotebookDocumentContentOptions): Disposable; + + /** + * Creates a new notebook controller. + * + * @param id Identifier of the controller. Must be unique per extension. + * @param notebookType A notebook type for which this controller is for. + * @param label The label of the controller. + * @param handler The execute-handler of the controller. + */ + export function createNotebookController(id: string, notebookType: string, label: string, handler?: NotebookExecuteHandler): NotebookController; + + /** + * Register a {@link NotebookCellStatusBarItemProvider cell statusbar item provider} for the given notebook type. + * + * @param notebookType The notebook type to register for. + * @param provider A cell status bar provider. + * @return A {@link Disposable} that unregisters this provider when being disposed. + */ + export function registerNotebookCellStatusBarItemProvider(notebookType: string, provider: NotebookCellStatusBarItemProvider): Disposable; + } + + /** + * Represents the input box in the Source Control viewlet. + */ + export interface SourceControlInputBox { + + /** + * Setter and getter for the contents of the input box. + */ + value: string; + + /** + * A string to show as placeholder in the input box to guide the user. + */ + placeholder: string; + + /** + * Controls whether the input box is visible (default is `true`). + */ + visible: boolean; + } + + interface QuickDiffProvider { + + /** + * Provide a {@link Uri} to the original resource of any given resource uri. + * + * @param uri The uri of the resource open in a text editor. + * @param token A cancellation token. + * @return A thenable that resolves to uri of the matching original resource. + */ + provideOriginalResource?(uri: Uri, token: CancellationToken): ProviderResult; + } + + /** + * The theme-aware decorations for a + * {@link SourceControlResourceState source control resource state}. + */ + export interface SourceControlResourceThemableDecorations { + + /** + * The icon path for a specific + * {@link SourceControlResourceState source control resource state}. + */ + readonly iconPath?: string | Uri; + } + + /** + * The decorations for a {@link SourceControlResourceState source control resource state}. + * Can be independently specified for light and dark themes. + */ + export interface SourceControlResourceDecorations extends SourceControlResourceThemableDecorations { + + /** + * Whether the {@link SourceControlResourceState source control resource state} should + * be striked-through in the UI. + */ + readonly strikeThrough?: boolean; + + /** + * Whether the {@link SourceControlResourceState source control resource state} should + * be faded in the UI. + */ + readonly faded?: boolean; + + /** + * The title for a specific + * {@link SourceControlResourceState source control resource state}. + */ + readonly tooltip?: string; + + /** + * The light theme decorations. + */ + readonly light?: SourceControlResourceThemableDecorations; + + /** + * The dark theme decorations. + */ + readonly dark?: SourceControlResourceThemableDecorations; + } + + /** + * An source control resource state represents the state of an underlying workspace + * resource within a certain {@link SourceControlResourceGroup source control group}. + */ + export interface SourceControlResourceState { + + /** + * The {@link Uri} of the underlying resource inside the workspace. + */ + readonly resourceUri: Uri; + + /** + * The {@link Command} which should be run when the resource + * state is open in the Source Control viewlet. + */ + readonly command?: Command; + + /** + * The {@link SourceControlResourceDecorations decorations} for this source control + * resource state. + */ + readonly decorations?: SourceControlResourceDecorations; + + /** + * Context value of the resource state. This can be used to contribute resource specific actions. + * For example, if a resource is given a context value as `diffable`. When contributing actions to `scm/resourceState/context` + * using `menus` extension point, you can specify context value for key `scmResourceState` in `when` expressions, like `scmResourceState == diffable`. + * ``` + * "contributes": { + * "menus": { + * "scm/resourceState/context": [ + * { + * "command": "extension.diff", + * "when": "scmResourceState == diffable" + * } + * ] + * } + * } + * ``` + * This will show action `extension.diff` only for resources with `contextValue` is `diffable`. + */ + readonly contextValue?: string; + } + + /** + * A source control resource group is a collection of + * {@link SourceControlResourceState source control resource states}. + */ + export interface SourceControlResourceGroup { + + /** + * The id of this source control resource group. + */ + readonly id: string; + + /** + * The label of this source control resource group. + */ + label: string; + + /** + * Whether this source control resource group is hidden when it contains + * no {@link SourceControlResourceState source control resource states}. + */ + hideWhenEmpty?: boolean; + + /** + * This group's collection of + * {@link SourceControlResourceState source control resource states}. + */ + resourceStates: SourceControlResourceState[]; + + /** + * Dispose this source control resource group. + */ + dispose(): void; + } + + /** + * An source control is able to provide {@link SourceControlResourceState resource states} + * to the editor and interact with the editor in several source control related ways. + */ + export interface SourceControl { + + /** + * The id of this source control. + */ + readonly id: string; + + /** + * The human-readable label of this source control. + */ + readonly label: string; + + /** + * The (optional) Uri of the root of this source control. + */ + readonly rootUri: Uri | undefined; + + /** + * The {@link SourceControlInputBox input box} for this source control. + */ + readonly inputBox: SourceControlInputBox; + + /** + * The UI-visible count of {@link SourceControlResourceState resource states} of + * this source control. + * + * Equals to the total number of {@link SourceControlResourceState resource state} + * of this source control, if undefined. + */ + count?: number; + + /** + * An optional {@link QuickDiffProvider quick diff provider}. + */ + quickDiffProvider?: QuickDiffProvider; + + /** + * Optional commit template string. + * + * The Source Control viewlet will populate the Source Control + * input with this value when appropriate. + */ + commitTemplate?: string; + + /** + * Optional accept input command. + * + * This command will be invoked when the user accepts the value + * in the Source Control input. + */ + acceptInputCommand?: Command; + + /** + * Optional status bar commands. + * + * These commands will be displayed in the editor's status bar. + */ + statusBarCommands?: Command[]; + + /** + * Create a new {@link SourceControlResourceGroup resource group}. + */ + createResourceGroup(id: string, label: string): SourceControlResourceGroup; + + /** + * Dispose this source control. + */ + dispose(): void; + } + + export namespace scm { + + /** + * The {@link SourceControlInputBox input box} for the last source control + * created by the extension. + * + * @deprecated Use SourceControl.inputBox instead + */ + export const inputBox: SourceControlInputBox; + + /** + * Creates a new {@link SourceControl source control} instance. + * + * @param id An `id` for the source control. Something short, e.g.: `git`. + * @param label A human-readable string for the source control. E.g.: `Git`. + * @param rootUri An optional Uri of the root of the source control. E.g.: `Uri.parse(workspaceRoot)`. + * @return An instance of {@link SourceControl source control}. + */ + export function createSourceControl(id: string, label: string, rootUri?: Uri): SourceControl; + } + + /** + * A DebugProtocolMessage is an opaque stand-in type for the [ProtocolMessage](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_ProtocolMessage) type defined in the Debug Adapter Protocol. + */ + export interface DebugProtocolMessage { + // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Base_Protocol_ProtocolMessage). + } + + /** + * A DebugProtocolSource is an opaque stand-in type for the [Source](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Source) type defined in the Debug Adapter Protocol. + */ + export interface DebugProtocolSource { + // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Source). + } + + /** + * A DebugProtocolBreakpoint is an opaque stand-in type for the [Breakpoint](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Breakpoint) type defined in the Debug Adapter Protocol. + */ + export interface DebugProtocolBreakpoint { + // Properties: see details [here](https://microsoft.github.io/debug-adapter-protocol/specification#Types_Breakpoint). + } + + /** + * Configuration for a debug session. + */ + export interface DebugConfiguration { + /** + * The type of the debug session. + */ + type: string; + + /** + * The name of the debug session. + */ + name: string; + + /** + * The request type of the debug session. + */ + request: string; + + /** + * Additional debug type specific properties. + */ + [key: string]: any; + } + + /** + * A debug session. + */ + export interface DebugSession { + + /** + * The unique ID of this debug session. + */ + readonly id: string; + + /** + * The debug session's type from the {@link DebugConfiguration debug configuration}. */ readonly type: string; /** - * The debug session's name is initially taken from the [debug configuration](#DebugConfiguration). + * The parent session of this debug session, if it was created as a child. + * @see DebugSessionOptions.parentSession + */ + readonly parentSession?: DebugSession; + + /** + * The debug session's name is initially taken from the {@link DebugConfiguration debug configuration}. * Any changes will be properly reflected in the UI. */ name: string; @@ -11554,7 +12615,7 @@ declare module 'vscode' { readonly workspaceFolder: WorkspaceFolder | undefined; /** - * The "resolved" [debug configuration](#DebugConfiguration) of this session. + * The "resolved" {@link DebugConfiguration debug configuration} of this session. * "Resolved" means that * - all variables have been substituted and * - platform specific attribute sections have been "flattened" for the matching platform and removed for non-matching platforms. @@ -11570,18 +12631,18 @@ declare module 'vscode' { * Maps a VS Code breakpoint to the corresponding Debug Adapter Protocol (DAP) breakpoint that is managed by the debug adapter of the debug session. * If no DAP breakpoint exists (either because the VS Code breakpoint was not yet registered or because the debug adapter is not interested in the breakpoint), the value `undefined` is returned. * - * @param breakpoint A VS Code [breakpoint](#Breakpoint). + * @param breakpoint A VS Code {@link Breakpoint}. * @return A promise that resolves to the Debug Adapter Protocol breakpoint or `undefined`. */ getDebugProtocolBreakpoint(breakpoint: Breakpoint): Thenable; } /** - * A custom Debug Adapter Protocol event received from a [debug session](#DebugSession). + * A custom Debug Adapter Protocol event received from a {@link DebugSession debug session}. */ export interface DebugSessionCustomEvent { /** - * The [debug session](#DebugSession) for which the custom event was received. + * The {@link DebugSession debug session} for which the custom event was received. */ readonly session: DebugSession; @@ -11599,28 +12660,28 @@ declare module 'vscode' { /** * A debug configuration provider allows to add debug configurations to the debug service * and to resolve launch configurations before they are used to start a debug session. - * A debug configuration provider is registered via #debug.registerDebugConfigurationProvider. + * A debug configuration provider is registered via {@link debug.registerDebugConfigurationProvider}. */ export interface DebugConfigurationProvider { /** - * Provides [debug configuration](#DebugConfiguration) to the debug service. If more than one debug configuration provider is + * Provides {@link DebugConfiguration debug configuration} to the debug service. If more than one debug configuration provider is * registered for the same type, debug configurations are concatenated in arbitrary order. * * @param folder The workspace folder for which the configurations are used or `undefined` for a folderless setup. * @param token A cancellation token. - * @return An array of [debug configurations](#DebugConfiguration). + * @return An array of {@link DebugConfiguration debug configurations}. */ provideDebugConfigurations?(folder: WorkspaceFolder | undefined, token?: CancellationToken): ProviderResult; /** - * Resolves a [debug configuration](#DebugConfiguration) by filling in missing values or by adding/changing/removing attributes. + * Resolves a {@link DebugConfiguration debug configuration} by filling in missing values or by adding/changing/removing attributes. * If more than one debug configuration provider is registered for the same type, the resolveDebugConfiguration calls are chained * in arbitrary order and the initial debug configuration is piped through the chain. * Returning the value 'undefined' prevents the debug session from starting. * Returning the value 'null' prevents the debug session from starting and opens the underlying debug configuration instead. * * @param folder The workspace folder from which the configuration originates from or `undefined` for a folderless setup. - * @param debugConfiguration The [debug configuration](#DebugConfiguration) to resolve. + * @param debugConfiguration The {@link DebugConfiguration debug configuration} to resolve. * @param token A cancellation token. * @return The resolved debug configuration or undefined or null. */ @@ -11628,14 +12689,14 @@ declare module 'vscode' { /** * This hook is directly called after 'resolveDebugConfiguration' but with all variables substituted. - * It can be used to resolve or verify a [debug configuration](#DebugConfiguration) by filling in missing values or by adding/changing/removing attributes. + * It can be used to resolve or verify a {@link DebugConfiguration debug configuration} by filling in missing values or by adding/changing/removing attributes. * If more than one debug configuration provider is registered for the same type, the 'resolveDebugConfigurationWithSubstitutedVariables' calls are chained * in arbitrary order and the initial debug configuration is piped through the chain. * Returning the value 'undefined' prevents the debug session from starting. * Returning the value 'null' prevents the debug session from starting and opens the underlying debug configuration instead. * * @param folder The workspace folder from which the configuration originates from or `undefined` for a folderless setup. - * @param debugConfiguration The [debug configuration](#DebugConfiguration) to resolve. + * @param debugConfiguration The {@link DebugConfiguration debug configuration} to resolve. * @param token A cancellation token. * @return The resolved debug configuration or undefined or null. */ @@ -11765,10 +12826,10 @@ declare module 'vscode' { export interface DebugAdapterDescriptorFactory { /** * 'createDebugAdapterDescriptor' is called at the start of a debug session to provide details about the debug adapter to use. - * These details must be returned as objects of type [DebugAdapterDescriptor](#DebugAdapterDescriptor). + * These details must be returned as objects of type {@link DebugAdapterDescriptor}. * Currently two types of debug adapters are supported: - * - a debug adapter executable is specified as a command path and arguments (see [DebugAdapterExecutable](#DebugAdapterExecutable)), - * - a debug adapter server reachable via a communication port (see [DebugAdapterServer](#DebugAdapterServer)). + * - a debug adapter executable is specified as a command path and arguments (see {@link DebugAdapterExecutable}), + * - a debug adapter server reachable via a communication port (see {@link DebugAdapterServer}). * If the method is not implemented the default behavior is this: * createDebugAdapter(session: DebugSession, executable: DebugAdapterExecutable) { * if (typeof session.configuration.debugServer === 'number') { @@ -11776,9 +12837,9 @@ declare module 'vscode' { * } * return executable; * } - * @param session The [debug session](#DebugSession) for which the debug adapter will be used. + * @param session The {@link DebugSession debug session} for which the debug adapter will be used. * @param executable The debug adapter's executable information as specified in the package.json (or undefined if no such information exists). - * @return a [debug adapter descriptor](#DebugAdapterDescriptor) or undefined. + * @return a {@link DebugAdapterDescriptor debug adapter descriptor} or undefined. */ createDebugAdapterDescriptor(session: DebugSession, executable: DebugAdapterExecutable | undefined): ProviderResult; } @@ -11818,8 +12879,8 @@ declare module 'vscode' { * The method 'createDebugAdapterTracker' is called at the start of a debug session in order * to return a "tracker" object that provides read-access to the communication between VS Code and a debug adapter. * - * @param session The [debug session](#DebugSession) for which the debug adapter tracker will be used. - * @return A [debug adapter tracker](#DebugAdapterTracker) or undefined. + * @param session The {@link DebugSession debug session} for which the debug adapter tracker will be used. + * @return A {@link DebugAdapterTracker debug adapter tracker} or undefined. */ createDebugAdapterTracker(session: DebugSession): ProviderResult; } @@ -11845,23 +12906,23 @@ declare module 'vscode' { } /** - * An event describing the changes to the set of [breakpoints](#Breakpoint). + * An event describing the changes to the set of {@link Breakpoint breakpoints}. */ export interface BreakpointsChangeEvent { /** * Added breakpoints. */ - readonly added: ReadonlyArray; + readonly added: readonly Breakpoint[]; /** * Removed breakpoints. */ - readonly removed: ReadonlyArray; + readonly removed: readonly Breakpoint[]; /** * Changed breakpoints. */ - readonly changed: ReadonlyArray; + readonly changed: readonly Breakpoint[]; } /** @@ -11923,7 +12984,7 @@ declare module 'vscode' { } /** - * Debug console mode used by debug session, see [options](#DebugSessionOptions). + * Debug console mode used by debug session, see {@link DebugSessionOptions options}. */ export enum DebugConsoleMode { /** @@ -11939,7 +13000,7 @@ declare module 'vscode' { } /** - * Options for [starting a debug session](#debug.startDebugging). + * Options for {@link debug.startDebugging starting a debug session}. */ export interface DebugSessionOptions { @@ -11974,7 +13035,7 @@ declare module 'vscode' { * A DebugConfigurationProviderTriggerKind specifies when the `provideDebugConfigurations` method of a `DebugConfigurationProvider` is triggered. * Currently there are two situations: to provide the initial debug configurations for a newly created launch.json or * to provide dynamically generated debug configurations when the user asks for them through the UI (e.g. via the "Select and Start Debugging" command). - * A trigger kind is used when registering a `DebugConfigurationProvider` with #debug.registerDebugConfigurationProvider. + * A trigger kind is used when registering a `DebugConfigurationProvider` with {@link debug.registerDebugConfigurationProvider}. */ export enum DebugConfigurationProviderTriggerKind { /** @@ -11993,14 +13054,14 @@ declare module 'vscode' { export namespace debug { /** - * The currently active [debug session](#DebugSession) or `undefined`. The active debug session is the one + * The currently active {@link DebugSession debug session} or `undefined`. The active debug session is the one * represented by the debug action floating window or the one currently shown in the drop down menu of the debug action floating window. * If no debug session is active, the value is `undefined`. */ export let activeDebugSession: DebugSession | undefined; /** - * The currently active [debug console](#DebugConsole). + * The currently active {@link DebugConsole debug console}. * If no debug session is active, output sent to the debug console is not shown. */ export let activeDebugConsole: DebugConsole; @@ -12011,35 +13072,35 @@ declare module 'vscode' { export let breakpoints: Breakpoint[]; /** - * An [event](#Event) which fires when the [active debug session](#debug.activeDebugSession) + * An {@link Event} which fires when the {@link debug.activeDebugSession active debug session} * has changed. *Note* that the event also fires when the active debug session changes * to `undefined`. */ export const onDidChangeActiveDebugSession: Event; /** - * An [event](#Event) which fires when a new [debug session](#DebugSession) has been started. + * An {@link Event} which fires when a new {@link DebugSession debug session} has been started. */ export const onDidStartDebugSession: Event; /** - * An [event](#Event) which fires when a custom DAP event is received from the [debug session](#DebugSession). + * An {@link Event} which fires when a custom DAP event is received from the {@link DebugSession debug session}. */ export const onDidReceiveDebugSessionCustomEvent: Event; /** - * An [event](#Event) which fires when a [debug session](#DebugSession) has terminated. + * An {@link Event} which fires when a {@link DebugSession debug session} has terminated. */ export const onDidTerminateDebugSession: Event; /** - * An [event](#Event) that is emitted when the set of breakpoints is added, removed, or changed. + * An {@link Event} that is emitted when the set of breakpoints is added, removed, or changed. */ export const onDidChangeBreakpoints: Event; /** - * Register a [debug configuration provider](#DebugConfigurationProvider) for a specific debug type. - * The optional [triggerKind](#DebugConfigurationProviderTriggerKind) can be used to specify when the `provideDebugConfigurations` method of the provider is triggered. + * Register a {@link DebugConfigurationProvider debug configuration provider} for a specific debug type. + * The optional {@link DebugConfigurationProviderTriggerKind triggerKind} can be used to specify when the `provideDebugConfigurations` method of the provider is triggered. * Currently two trigger kinds are possible: with the value `Initial` (or if no trigger kind argument is given) the `provideDebugConfigurations` method is used to provide the initial debug configurations to be copied into a newly created launch.json. * With the trigger kind `Dynamic` the `provideDebugConfigurations` method is used to dynamically determine debug configurations to be presented to the user (in addition to the static configurations from the launch.json). * Please note that the `triggerKind` argument only applies to the `provideDebugConfigurations` method: so the `resolveDebugConfiguration` methods are not affected at all. @@ -12047,20 +13108,20 @@ declare module 'vscode' { * More than one provider can be registered for the same type. * * @param type The debug type for which the provider is registered. - * @param provider The [debug configuration provider](#DebugConfigurationProvider) to register. - * @param triggerKind The [trigger](#DebugConfigurationProviderTrigger) for which the 'provideDebugConfiguration' method of the provider is registered. If `triggerKind` is missing, the value `DebugConfigurationProviderTriggerKind.Initial` is assumed. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @param provider The {@link DebugConfigurationProvider debug configuration provider} to register. + * @param triggerKind The {@link DebugConfigurationProviderTrigger trigger} for which the 'provideDebugConfiguration' method of the provider is registered. If `triggerKind` is missing, the value `DebugConfigurationProviderTriggerKind.Initial` is assumed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerDebugConfigurationProvider(debugType: string, provider: DebugConfigurationProvider, triggerKind?: DebugConfigurationProviderTriggerKind): Disposable; /** - * Register a [debug adapter descriptor factory](#DebugAdapterDescriptorFactory) for a specific debug type. + * Register a {@link DebugAdapterDescriptorFactory debug adapter descriptor factory} for a specific debug type. * An extension is only allowed to register a DebugAdapterDescriptorFactory for the debug type(s) defined by the extension. Otherwise an error is thrown. * Registering more than one DebugAdapterDescriptorFactory for a debug type results in an error. * * @param debugType The debug type for which the factory is registered. - * @param factory The [debug adapter descriptor factory](#DebugAdapterDescriptorFactory) to register. - * @return A [disposable](#Disposable) that unregisters this factory when being disposed. + * @param factory The {@link DebugAdapterDescriptorFactory debug adapter descriptor factory} to register. + * @return A {@link Disposable} that unregisters this factory when being disposed. */ export function registerDebugAdapterDescriptorFactory(debugType: string, factory: DebugAdapterDescriptorFactory): Disposable; @@ -12068,27 +13129,27 @@ declare module 'vscode' { * Register a debug adapter tracker factory for the given debug type. * * @param debugType The debug type for which the factory is registered or '*' for matching all debug types. - * @param factory The [debug adapter tracker factory](#DebugAdapterTrackerFactory) to register. - * @return A [disposable](#Disposable) that unregisters this factory when being disposed. + * @param factory The {@link DebugAdapterTrackerFactory debug adapter tracker factory} to register. + * @return A {@link Disposable} that unregisters this factory when being disposed. */ export function registerDebugAdapterTrackerFactory(debugType: string, factory: DebugAdapterTrackerFactory): Disposable; /** * Start debugging by using either a named launch or named compound configuration, - * or by directly passing a [DebugConfiguration](#DebugConfiguration). + * or by directly passing a {@link DebugConfiguration}. * The named configurations are looked up in '.vscode/launch.json' found in the given folder. * Before debugging starts, all unsaved files are saved and the launch configurations are brought up-to-date. * Folder specific variables used in the configuration (e.g. '${workspaceFolder}') are resolved against the given folder. - * @param folder The [workspace folder](#WorkspaceFolder) for looking up named configurations and resolving variables or `undefined` for a non-folder setup. - * @param nameOrConfiguration Either the name of a debug or compound configuration or a [DebugConfiguration](#DebugConfiguration) object. - * @param parentSessionOrOptions Debug session options. When passed a parent [debug session](#DebugSession), assumes options with just this parent session. + * @param folder The {@link WorkspaceFolder workspace folder} for looking up named configurations and resolving variables or `undefined` for a non-folder setup. + * @param nameOrConfiguration Either the name of a debug or compound configuration or a {@link DebugConfiguration} object. + * @param parentSessionOrOptions Debug session options. When passed a parent {@link DebugSession debug session}, assumes options with just this parent session. * @return A thenable that resolves when debugging could be successfully started. */ export function startDebugging(folder: WorkspaceFolder | undefined, nameOrConfiguration: string | DebugConfiguration, parentSessionOrOptions?: DebugSession | DebugSessionOptions): Thenable; /** * Stop the given debug session or stop all debug sessions if session is omitted. - * @param session The [debug session](#DebugSession) to stop; if omitted all sessions are stopped. + * @param session The {@link DebugSession debug session} to stop; if omitted all sessions are stopped. */ export function stopDebugging(session?: DebugSession): Thenable; @@ -12096,13 +13157,13 @@ declare module 'vscode' { * Add breakpoints. * @param breakpoints The breakpoints to add. */ - export function addBreakpoints(breakpoints: Breakpoint[]): void; + export function addBreakpoints(breakpoints: readonly Breakpoint[]): void; /** * Remove breakpoints. * @param breakpoints The breakpoints to remove. */ - export function removeBreakpoints(breakpoints: Breakpoint[]): void; + export function removeBreakpoints(breakpoints: readonly Breakpoint[]): void; /** * Converts a "Source" descriptor object received via the Debug Adapter Protocol into a Uri that can be used to load its contents. @@ -12120,7 +13181,7 @@ declare module 'vscode' { /** * Namespace for dealing with installed extensions. Extensions are represented - * by an [extension](#Extension)-interface which enables reflection on them. + * by an {@link Extension}-interface which enables reflection on them. * * Extension writers can provide APIs to other extensions by returning their API public * surface from the `activate`-call. @@ -12140,8 +13201,8 @@ declare module 'vscode' { * } * ``` * When depending on the API of another extension add an `extensionDependencies`-entry - * to `package.json`, and use the [getExtension](#extensions.getExtension)-function - * and the [exports](#Extension.exports)-property, like below: + * to `package.json`, and use the {@link extensions.getExtension getExtension}-function + * and the {@link Extension.exports exports}-property, like below: * * ```javascript * let mathExt = extensions.getExtension('genius.math'); @@ -12171,7 +13232,7 @@ declare module 'vscode' { /** * All extensions currently known to the system. */ - export const all: ReadonlyArray>; + export const all: readonly Extension[]; /** * An event which fires when `extensions.all` changes. This can happen when extensions are @@ -12181,7 +13242,7 @@ declare module 'vscode' { } /** - * Collapsible state of a [comment thread](#CommentThread) + * Collapsible state of a {@link CommentThread comment thread} */ export enum CommentThreadCollapsibleState { /** @@ -12196,7 +13257,7 @@ declare module 'vscode' { } /** - * Comment mode of a [comment](#Comment) + * Comment mode of a {@link Comment} */ export enum CommentMode { /** @@ -12211,7 +13272,7 @@ declare module 'vscode' { } /** - * A collection of [comments](#Comment) representing a conversation at a particular range in a document. + * A collection of {@link Comment comments} representing a conversation at a particular range in a document. */ export interface CommentThread { /** @@ -12228,7 +13289,7 @@ declare module 'vscode' { /** * The ordered comments of the thread. */ - comments: ReadonlyArray; + comments: readonly Comment[]; /** * Whether the thread should be collapsed or expanded when opening the document. @@ -12263,7 +13324,7 @@ declare module 'vscode' { contextValue?: string; /** - * The optional human-readable label describing the [Comment Thread](#CommentThread) + * The optional human-readable label describing the {@link CommentThread Comment Thread} */ label?: string; @@ -12276,7 +13337,7 @@ declare module 'vscode' { } /** - * Author information of a [comment](#Comment) + * Author information of a {@link Comment} */ export interface CommentAuthorInformation { /** @@ -12291,7 +13352,7 @@ declare module 'vscode' { } /** - * Reactions of a [comment](#Comment) + * Reactions of a {@link Comment} */ export interface CommentReaction { /** @@ -12325,12 +13386,12 @@ declare module 'vscode' { body: string | MarkdownString; /** - * [Comment mode](#CommentMode) of the comment + * {@link CommentMode Comment mode} of the comment */ mode: CommentMode; /** - * The [author information](#CommentAuthorInformation) of the comment + * The {@link CommentAuthorInformation author information} of the comment */ author: CommentAuthorInformation; @@ -12355,12 +13416,12 @@ declare module 'vscode' { contextValue?: string; /** - * Optional reactions of the [comment](#Comment) + * Optional reactions of the {@link Comment} */ reactions?: CommentReaction[]; /** - * Optional label describing the [Comment](#Comment) + * Optional label describing the {@link Comment} * Label will be rendered next to authorName if exists. */ label?: string; @@ -12371,7 +13432,7 @@ declare module 'vscode' { */ export interface CommentReply { /** - * The active [comment thread](#CommentThread) + * The active {@link CommentThread comment thread} */ thread: CommentThread; @@ -12382,7 +13443,7 @@ declare module 'vscode' { } /** - * Commenting range provider for a [comment controller](#CommentController). + * Commenting range provider for a {@link CommentController comment controller}. */ export interface CommentingRangeProvider { /** @@ -12392,7 +13453,7 @@ declare module 'vscode' { } /** - * Represents a [comment controller](#CommentController)'s [options](#CommentController.options). + * Represents a {@link CommentController comment controller}'s {@link CommentController.options options}. */ export interface CommentOptions { /** @@ -12407,7 +13468,7 @@ declare module 'vscode' { } /** - * A comment controller is able to provide [comments](#CommentThread) support to the editor and + * A comment controller is able to provide {@link CommentThread comments} support to the editor and * provide users various ways to interact with comments. */ export interface CommentController { @@ -12427,31 +13488,31 @@ declare module 'vscode' { options?: CommentOptions; /** - * Optional commenting range provider. Provide a list [ranges](#Range) which support commenting to any given resource uri. + * Optional commenting range provider. Provide a list {@link Range ranges} which support commenting to any given resource uri. * * If not provided, users can leave comments in any document opened in the editor. */ commentingRangeProvider?: CommentingRangeProvider; /** - * Create a [comment thread](#CommentThread). The comment thread will be displayed in visible text editors (if the resource matches) + * Create a {@link CommentThread comment thread}. The comment thread will be displayed in visible text editors (if the resource matches) * and Comments Panel once created. * * @param uri The uri of the document the thread has been created on. * @param range The range the comment thread is located within the document. * @param comments The ordered comments of the thread. */ - createCommentThread(uri: Uri, range: Range, comments: Comment[]): CommentThread; + createCommentThread(uri: Uri, range: Range, comments: readonly Comment[]): CommentThread; /** - * Optional reaction handler for creating and deleting reactions on a [comment](#Comment). + * Optional reaction handler for creating and deleting reactions on a {@link Comment}. */ reactionHandler?: (comment: Comment, reaction: CommentReaction) => Thenable; /** * Dispose this comment controller. * - * Once disposed, all [comment threads](#CommentThread) created by this comment controller will also be removed from the editor + * Once disposed, all {@link CommentThread comment threads} created by this comment controller will also be removed from the editor * and Comments Panel. */ dispose(): void; @@ -12459,11 +13520,11 @@ declare module 'vscode' { namespace comments { /** - * Creates a new [comment controller](#CommentController) instance. + * Creates a new {@link CommentController comment controller} instance. * * @param id An `id` for the comment controller. * @param label A human-readable string for the comment controller. - * @return An instance of [comment controller](#CommentController). + * @return An instance of {@link CommentController comment controller}. */ export function createCommentController(id: string, label: string): CommentController; } @@ -12491,13 +13552,13 @@ declare module 'vscode' { /** * The permissions granted by the session's access token. Available scopes - * are defined by the [AuthenticationProvider](#AuthenticationProvider). + * are defined by the {@link AuthenticationProvider}. */ - readonly scopes: ReadonlyArray; + readonly scopes: readonly string[]; } /** - * The information of an account associated with an [AuthenticationSession](#AuthenticationSession). + * The information of an account associated with an {@link AuthenticationSession}. */ export interface AuthenticationSessionAccountInformation { /** @@ -12513,7 +13574,7 @@ declare module 'vscode' { /** - * Options to be used when getting an [AuthenticationSession](#AuthenticationSession) from an [AuthenticationProvider](#AuthenticationProvider). + * Options to be used when getting an {@link AuthenticationSession} from an {@link AuthenticationProvider}. */ export interface AuthenticationGetSessionOptions { /** @@ -12534,8 +13595,8 @@ declare module 'vscode' { * Whether the existing user session preference should be cleared. * * For authentication providers that support being signed into multiple accounts at once, the user will be - * prompted to select an account to use when [getSession](#authentication.getSession) is called. This preference - * is remembered until [getSession](#authentication.getSession) is called with this flag. + * prompted to select an account to use when {@link authentication.getSession getSession} is called. This preference + * is remembered until {@link authentication.getSession getSession} is called with this flag. * * Defaults to false. */ @@ -12543,7 +13604,7 @@ declare module 'vscode' { } /** - * Basic information about an [authenticationProvider](#AuthenticationProvider) + * Basic information about an {@link AuthenticationProvider} */ export interface AuthenticationProviderInformation { /** @@ -12558,17 +13619,17 @@ declare module 'vscode' { } /** - * An [event](#Event) which fires when an [AuthenticationSession](#AuthenticationSession) is added, removed, or changed. + * An {@link Event} which fires when an {@link AuthenticationSession} is added, removed, or changed. */ export interface AuthenticationSessionsChangeEvent { /** - * The [authenticationProvider](#AuthenticationProvider) that has had its sessions change. + * The {@link AuthenticationProvider} that has had its sessions change. */ readonly provider: AuthenticationProviderInformation; } /** - * Options for creating an [AuthenticationProvider](#AuthenticationProvider). + * Options for creating an {@link AuthenticationProvider}. */ export interface AuthenticationProviderOptions { /** @@ -12579,25 +13640,25 @@ declare module 'vscode' { } /** - * An [event](#Event) which fires when an [AuthenticationSession](#AuthenticationSession) is added, removed, or changed. + * An {@link Event} which fires when an {@link AuthenticationSession} is added, removed, or changed. */ export interface AuthenticationProviderAuthenticationSessionsChangeEvent { /** - * The [AuthenticationSession](#AuthenticationSession)s of the [AuthenticationProvider](#AuthentiationProvider) that have been added. + * The {@link AuthenticationSession}s of the {@link AuthentiationProvider AuthenticationProvider} that have been added. */ - readonly added?: ReadonlyArray; + readonly added?: readonly AuthenticationSession[]; /** - * The [AuthenticationSession](#AuthenticationSession)s of the [AuthenticationProvider](#AuthentiationProvider) that have been removed. + * The {@link AuthenticationSession}s of the {@link AuthentiationProvider AuthenticationProvider} that have been removed. */ - readonly removed?: ReadonlyArray; + readonly removed?: readonly AuthenticationSession[]; /** - * The [AuthenticationSession](#AuthenticationSession)s of the [AuthenticationProvider](#AuthentiationProvider) that have been changed. + * The {@link AuthenticationSession}s of the {@link AuthentiationProvider AuthenticationProvider} that have been changed. * A session changes when its data excluding the id are updated. An example of this is a session refresh that results in a new * access token being set for the session. */ - readonly changed?: ReadonlyArray; + readonly changed?: readonly AuthenticationSession[]; } /** @@ -12605,7 +13666,7 @@ declare module 'vscode' { */ export interface AuthenticationProvider { /** - * An [event](#Event) which fires when the array of sessions has changed, or data + * An {@link Event} which fires when the array of sessions has changed, or data * within a session has changed. */ readonly onDidChangeSessions: Event; @@ -12616,7 +13677,7 @@ declare module 'vscode' { * these permissions, otherwise all sessions should be returned. * @returns A promise that resolves to an array of authentication sessions. */ - getSessions(scopes?: string[]): Thenable>; + getSessions(scopes?: readonly string[]): Thenable; /** * Prompts a user to login. @@ -12631,7 +13692,7 @@ declare module 'vscode' { * @param scopes A list of scopes, permissions, that the new session should be created with. * @returns A promise that resolves to an authentication session. */ - createSession(scopes: string[]): Thenable; + createSession(scopes: readonly string[]): Thenable; /** * Removes the session corresponding to session id. @@ -12659,10 +13720,10 @@ declare module 'vscode' { * to VS Code that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'. * @param providerId The id of the provider to use * @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider - * @param options The [getSessionOptions](#GetSessionOptions) to use + * @param options The {@link GetSessionOptions} to use * @returns A thenable that resolves to an authentication session */ - export function getSession(providerId: string, scopes: string[], options: AuthenticationGetSessionOptions & { createIfNone: true }): Thenable; + export function getSession(providerId: string, scopes: readonly string[], options: AuthenticationGetSessionOptions & { createIfNone: true }): Thenable; /** * Get an authentication session matching the desired scopes. Rejects if a provider with providerId is not @@ -12674,13 +13735,13 @@ declare module 'vscode' { * to VS Code that implement GitHub and Microsoft authentication: their providerId's are 'github' and 'microsoft'. * @param providerId The id of the provider to use * @param scopes A list of scopes representing the permissions requested. These are dependent on the authentication provider - * @param options The [getSessionOptions](#GetSessionOptions) to use + * @param options The {@link GetSessionOptions} to use * @returns A thenable that resolves to an authentication session if available, or undefined if there are no sessions */ - export function getSession(providerId: string, scopes: string[], options?: AuthenticationGetSessionOptions): Thenable; + export function getSession(providerId: string, scopes: readonly string[], options?: AuthenticationGetSessionOptions): Thenable; /** - * An [event](#Event) which fires when the authentication sessions of an authentication provider have + * An {@link Event} which fires when the authentication sessions of an authentication provider have * been added, removed, or changed. */ export const onDidChangeSessions: Event; @@ -12695,7 +13756,7 @@ declare module 'vscode' { * @param label The human-readable name of the provider. * @param provider The authentication provider provider. * @params options Additional options for the provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerAuthenticationProvider(id: string, label: string, provider: AuthenticationProvider, options?: AuthenticationProviderOptions): Disposable; } diff --git a/src/typings/vscode.proposed.d.ts b/src/typings/vscode.proposed.d.ts index 6871adcd2..6b313833a 100644 --- a/src/typings/vscode.proposed.d.ts +++ b/src/typings/vscode.proposed.d.ts @@ -19,16 +19,16 @@ declare module 'vscode' { //#region auth provider: https://github.com/microsoft/vscode/issues/88309 /** - * An [event](#Event) which fires when an [AuthenticationProvider](#AuthenticationProvider) is added or removed. + * An {@link Event} which fires when an {@link AuthenticationProvider} is added or removed. */ export interface AuthenticationProvidersChangeEvent { /** - * The ids of the [authenticationProvider](#AuthenticationProvider)s that have been added. + * The ids of the {@link AuthenticationProvider}s that have been added. */ readonly added: ReadonlyArray; /** - * The ids of the [authenticationProvider](#AuthenticationProvider)s that have been removed. + * The ids of the {@link AuthenticationProvider}s that have been removed. */ readonly removed: ReadonlyArray; } @@ -80,16 +80,10 @@ declare module 'vscode' { constructor(host: string, port: number, connectionToken?: string); } - export enum RemoteTrustOption { - Unknown = 0, - DisableTrust = 1, - MachineTrusted = 2 - } - export interface ResolvedOptions { extensionHostEnv?: { [key: string]: string | null; }; - trust?: RemoteTrustOption; + isTrusted?: boolean; } export interface TunnelOptions { @@ -150,7 +144,24 @@ declare module 'vscode' { } export interface RemoteAuthorityResolver { + /** + * Resolve the authority part of the current opened `vscode-remote://` URI. + * + * This method will be invoked once during the startup of VS Code and again each time + * VS Code detects a disconnection. + * + * @param authority The authority part of the current opened `vscode-remote://` URI. + * @param context A context indicating if this is the first call or a subsequent call. + */ resolve(authority: string, context: RemoteAuthorityResolverContext): ResolverResult | Thenable; + + /** + * Get the canonical URI (if applicable) for a `vscode-remote://` URI. + * + * @returns The canonical URI or undefined if the uri is already canonical. + */ + getCanonicalURI?(uri: Uri): ProviderResult; + /** * Can be optionally implemented if the extension can forward ports better than the core. * When not implemented, the core will use its default forwarding logic. @@ -289,7 +300,7 @@ declare module 'vscode' { /** * A file glob pattern to match file paths against. * TODO@roblourens merge this with the GlobPattern docs/definition in vscode.d.ts. - * @see [GlobPattern](#GlobPattern) + * @see {@link GlobPattern} */ export type GlobString = string; @@ -384,18 +395,56 @@ declare module 'vscode' { afterContext?: number; } + /** + * Represents the severiry of a TextSearchComplete message. + */ + export enum TextSearchCompleteMessageType { + Information = 1, + Warning = 2, + } + + /** + * A message regarding a completed search. + */ + export interface TextSearchCompleteMessage { + /** + * Markdown text of the message. + */ + text: string, + /** + * Whether the source of the message is trusted, command links are disabled for untrusted message sources. + * Messaged are untrusted by default. + */ + trusted?: boolean, + /** + * The message type, this affects how the message will be rendered. + */ + type: TextSearchCompleteMessageType, + } + /** * Information collected when text search is complete. */ export interface TextSearchComplete { /** * Whether the search hit the limit on the maximum number of search results. - * `maxResults` on [`TextSearchOptions`](#TextSearchOptions) specifies the max number of results. + * `maxResults` on {@link TextSearchOptions `TextSearchOptions`} specifies the max number of results. * - If exactly that number of matches exist, this should be false. * - If `maxResults` matches are returned and more exist, this should be true. * - If search hits an internal limit which is less than `maxResults`, this should be true. */ limitHit?: boolean; + + /** + * Additional information regarding the state of the completed search. + * + * Messages with "Information" tyle support links in markdown syntax: + * - Click to [run a command](command:workbench.action.OpenQuickPick) + * - Click to [open a website](https://aka.ms) + * + * Commands may optionally return { triggerSearch: true } to signal to VS Code that the original search should run be agian. + */ + message?: TextSearchCompleteMessage | TextSearchCompleteMessage[]; } /** @@ -528,7 +577,7 @@ declare module 'vscode' { * * @param scheme The provider will be invoked for workspace folders that have this file scheme. * @param provider The provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerFileSearchProvider(scheme: string, provider: FileSearchProvider): Disposable; @@ -539,7 +588,7 @@ declare module 'vscode' { * * @param scheme The provider will be invoked for workspace folders that have this file scheme. * @param provider The provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerTextSearchProvider(scheme: string, provider: TextSearchProvider): Disposable; } @@ -553,14 +602,14 @@ declare module 'vscode' { */ export interface FindTextInFilesOptions { /** - * A [glob pattern](#GlobPattern) that defines the files to search for. The glob pattern - * will be matched against the file paths of files relative to their workspace. Use a [relative pattern](#RelativePattern) - * to restrict the search results to a [workspace folder](#WorkspaceFolder). + * A {@link GlobPattern glob pattern} that defines the files to search for. The glob pattern + * will be matched against the file paths of files relative to their workspace. Use a {@link RelativePattern relative pattern} + * to restrict the search results to a {@link WorkspaceFolder workspace folder}. */ include?: GlobPattern; /** - * A [glob pattern](#GlobPattern) that defines files and folders to exclude. The glob pattern + * A {@link GlobPattern glob pattern} that defines files and folders to exclude. The glob pattern * will be matched against the file paths of resulting matches relative to their workspace. When `undefined`, default excludes will * apply. */ @@ -618,7 +667,7 @@ declare module 'vscode' { export namespace workspace { /** - * Search text in files across all [workspace folders](#workspace.workspaceFolders) in the workspace. + * Search text in files across all {@link workspace.workspaceFolders workspace folders} in the workspace. * @param query The query parameters for the search - the search string, whether it's case-sensitive, or a regex, or matches whole words. * @param callback A callback, called for each result * @param token A token that can be used to signal cancellation to the underlying search engine. @@ -627,7 +676,7 @@ declare module 'vscode' { export function findTextInFiles(query: TextSearchQuery, callback: (result: TextSearchResult) => void, token?: CancellationToken): Thenable; /** - * Search text in files across all [workspace folders](#workspace.workspaceFolders) in the workspace. + * Search text in files across all {@link workspace.workspaceFolders workspace folders} in the workspace. * @param query The query parameters for the search - the search string, whether it's case-sensitive, or a regex, or matches whole words. * @param options An optional set of query options. Include and exclude patterns, maxResults, etc. * @param callback A callback, called for each result @@ -657,13 +706,13 @@ declare module 'vscode' { * Registers a diff information command that can be invoked via a keyboard shortcut, * a menu item, an action, or directly. * - * Diff information commands are different from ordinary [commands](#commands.registerCommand) as + * Diff information commands are different from ordinary {@link commands.registerCommand commands} as * they only execute when there is an active diff editor when the command is called, and the diff * information has been computed. Also, the command handler of an editor command has access to * the diff information. * * @param command A unique identifier for the command. - * @param callback A command handler function with access to the [diff information](#LineChange). + * @param callback A command handler function with access to the {@link LineChange diff information}. * @param thisArg The `this` context used when invoking the handler function. * @return Disposable which unregisters this command on disposal. */ @@ -771,7 +820,7 @@ declare module 'vscode' { export interface TerminalDataWriteEvent { /** - * The [terminal](#Terminal) for which the data was written. + * The {@link Terminal} for which the data was written. */ readonly terminal: Terminal; /** @@ -794,22 +843,22 @@ declare module 'vscode' { //#region Terminal dimensions property and change event https://github.com/microsoft/vscode/issues/55718 /** - * An [event](#Event) which fires when a [Terminal](#Terminal)'s dimensions change. + * An {@link Event} which fires when a {@link Terminal}'s dimensions change. */ export interface TerminalDimensionsChangeEvent { /** - * The [terminal](#Terminal) for which the dimensions have changed. + * The {@link Terminal} for which the dimensions have changed. */ readonly terminal: Terminal; /** - * The new value for the [terminal's dimensions](#Terminal.dimensions). + * The new value for the {@link Terminal.dimensions terminal's dimensions}. */ readonly dimensions: TerminalDimensions; } export namespace window { /** - * An event which fires when the [dimensions](#Terminal.dimensions) of the terminal change. + * An event which fires when the {@link Terminal.dimensions dimensions} of the terminal change. */ export const onDidChangeTerminalDimensions: Event; } @@ -825,15 +874,26 @@ declare module 'vscode' { //#endregion - //#region Terminal initial text https://github.com/microsoft/vscode/issues/120368 + //#region Terminal name change event https://github.com/microsoft/vscode/issues/114898 - export interface TerminalOptions { + export interface Pseudoterminal { /** - * A message to write to the terminal on first launch, note that this is not sent to the - * process but, rather written directly to the terminal. This supports escape sequences such - * a setting text style. + * An event that when fired allows changing the name of the terminal. + * + * **Example:** Change the terminal name to "My new terminal". + * ```typescript + * const writeEmitter = new vscode.EventEmitter(); + * const changeNameEmitter = new vscode.EventEmitter(); + * const pty: vscode.Pseudoterminal = { + * onDidWrite: writeEmitter.event, + * onDidChangeName: changeNameEmitter.event, + * open: () => changeNameEmitter.fire('My new terminal'), + * close: () => {} + * }; + * vscode.window.createTerminal({ name: 'My terminal', pty }); + * ``` */ - readonly message?: string; + onDidChangeName?: Event; } //#endregion @@ -842,9 +902,37 @@ declare module 'vscode' { export interface TerminalOptions { /** - * A codicon ID to associate with this terminal. + * The icon path or {@link ThemeIcon} for the terminal. + */ + readonly iconPath?: Uri | { light: Uri; dark: Uri } | { id: string, color?: { id: string } }; + } + + export interface ExtensionTerminalOptions { + /** + * A themeIcon, Uri, or light and dark Uris to use as the terminal tab icon + */ + readonly iconPath?: Uri | { light: Uri; dark: Uri } | { id: string, color?: { id: string } }; + } + + //#endregion + + //#region Terminal profile provider https://github.com/microsoft/vscode/issues/120369 + + export namespace window { + /** + * Registers a provider for a contributed terminal profile. + * @param id The ID of the contributed terminal profile. + * @param provider The terminal profile provider. */ - readonly icon?: string; + export function registerTerminalProfileProvider(id: string, provider: TerminalProfileProvider): Disposable; + } + + export interface TerminalProfileProvider { + /** + * Provide terminal profile options for the requested terminal. + * @param token A cancellation token that indicates the result is no longer needed. + */ + provideProfileOptions(token: CancellationToken): ProviderResult; } //#endregion @@ -864,66 +952,29 @@ declare module 'vscode' { } //#endregion - //#region Task presentation group: https://github.com/microsoft/vscode/issues/47265 - export interface TaskPresentationOptions { - /** - * Controls whether the task is executed in a specific terminal group using split panes. - */ - group?: string; + //#region Custom Tree View Drag and Drop https://github.com/microsoft/vscode/issues/32592 + export interface TreeViewOptions { + dragAndDropController?: DragAndDropController; } - //#endregion - - //#region Status bar item with ID and Name: https://github.com/microsoft/vscode/issues/74972 - - /** - * Options to configure the status bar item. - */ - export interface StatusBarItemOptions { - - /** - * A unique identifier of the status bar item. The identifier - * is for example used to allow a user to show or hide the - * status bar item in the UI. - */ - id: string; - - /** - * A human readable name of the status bar item. The name is - * for example used as a label in the UI to show or hide the - * status bar item. - */ - name: string; - - /** - * Accessibility information used when screen reader interacts with this status bar item. - */ - accessibilityInformation?: AccessibilityInformation; - - /** - * The alignment of the status bar item. - */ - alignment?: StatusBarAlignment; + export interface DragAndDropController extends Disposable { /** - * The priority of the status bar item. Higher value means the item should - * be shown more to the left. + * Extensions should fire `TreeDataProvider.onDidChangeTreeData` for any elements that need to be refreshed. + * + * @param source + * @param target */ - priority?: number; + onDrop(source: T[], target: T): Thenable; } + //#endregion - export namespace window { - + //#region Task presentation group: https://github.com/microsoft/vscode/issues/47265 + export interface TaskPresentationOptions { /** - * Creates a status bar [item](#StatusBarItem). - * - * @param options The options of the item. If not provided, some default values - * will be assumed. For example, the `StatusBarItemOptions.id` will be the id - * of the extension and the `StatusBarItemOptions.name` will be the extension name. - * @return A new status bar item. + * Controls whether the task is executed in a specific terminal group using split panes. */ - export function createStatusBarItem(options?: StatusBarItemOptions): StatusBarItem; + group?: string; } - //#endregion //#region Custom editor move https://github.com/microsoft/vscode/issues/86146 @@ -961,239 +1012,73 @@ declare module 'vscode' { //#endregion - //#region https://github.com/microsoft/vscode/issues/106744, Notebooks (misc) - - export enum NotebookCellKind { - Markdown = 1, - Code = 2 - } - - export class NotebookCellMetadata { - /** - * Whether a code cell's editor is collapsed - */ - readonly inputCollapsed?: boolean; + //#region https://github.com/microsoft/vscode/issues/124970, Cell Execution State + /** + * The execution state of a notebook cell. + */ + export enum NotebookCellExecutionState { /** - * Whether a code cell's outputs are collapsed + * The cell is idle. */ - readonly outputCollapsed?: boolean; - + Idle = 1, /** - * @deprecated - * Additional attributes of a cell metadata. + * Execution for the cell is pending. */ - readonly custom?: Record; - + Pending = 2, /** - * Additional attributes of a cell metadata. + * The cell is currently executing. */ - readonly [key: string]: any; - - constructor(inputCollapsed?: boolean, outputCollapsed?: boolean, custom?: Record); - - with(change: { inputCollapsed?: boolean | null, outputCollapsed?: boolean | null, custom?: Record | null, [key: string]: any }): NotebookCellMetadata; - } - - export interface NotebookCellExecutionSummary { - readonly executionOrder?: number; - readonly success?: boolean; - readonly startTime?: number; - readonly endTime?: number; - } - - // todo@API support ids https://github.com/jupyter/enhancement-proposals/blob/master/62-cell-id/cell-id.md - export interface NotebookCell { - readonly index: number; - readonly notebook: NotebookDocument; - readonly kind: NotebookCellKind; - readonly document: TextDocument; - readonly metadata: NotebookCellMetadata - readonly outputs: ReadonlyArray; - readonly latestExecutionSummary: NotebookCellExecutionSummary | undefined; + Executing = 3, } - export class NotebookDocumentMetadata { - /** - * @deprecated - * Additional attributes of the document metadata. - */ - readonly custom: { [key: string]: any; }; + /** + * An event describing a cell execution state change. + */ + export interface NotebookCellExecutionStateChangeEvent { /** - * Whether the document is trusted, default to true - * When false, insecure outputs like HTML, JavaScript, SVG will not be rendered. + * The {@link NotebookCell cell} for which the execution state has changed. */ - readonly trusted: boolean; + readonly cell: NotebookCell; /** - * Additional attributes of the document metadata. + * The new execution state of the cell. */ - readonly [key: string]: any; - - constructor(trusted?: boolean, custom?: { [key: string]: any; }); - - with(change: { trusted?: boolean | null, custom?: { [key: string]: any; } | null, [key: string]: any }): NotebookDocumentMetadata + readonly state: NotebookCellExecutionState; } - export interface NotebookDocumentContentOptions { - /** - * Controls if outputs change will trigger notebook document content change and if it will be used in the diff editor - * Default to false. If the content provider doesn't persisit the outputs in the file document, this should be set to true. - */ - transientOutputs?: boolean; - - /** - * @deprecated use transientCellMetadata instead - */ - transientMetadata?: { [K in keyof NotebookCellMetadata]?: boolean }; + export namespace notebooks { /** - * Controls if a cell metadata property change will trigger notebook document content change and if it will be used in the diff editor - * Default to false. If the content provider doesn't persisit a metadata property in the file document, it should be set to true. + * An {@link Event} which fires when the execution state of a cell has changed. */ - transientCellMetadata?: { [K in keyof NotebookCellMetadata]?: boolean }; - - /** - * Controls if a document metadata property change will trigger notebook document content change and if it will be used in the diff editor - * Default to false. If the content provider doesn't persisit a metadata property in the file document, it should be set to true. - */ - transientDocumentMetadata?: { [K in keyof NotebookDocumentMetadata]?: boolean }; + // todo@API this is an event that is fired for a property that cells don't have and that makes me wonder + // how a correct consumer works, e.g the consumer could have been late and missed an event? + export const onDidChangeNotebookCellExecutionState: Event; } - export interface NotebookDocumentContentOptions { - /** - * Not ready for production or development use yet. - */ - viewOptions?: { - displayName: string; - filenamePattern: NotebookFilenamePattern[]; - exclusive?: boolean; - }; - } + //#endregion + + //#region https://github.com/microsoft/vscode/issues/106744, Notebook, deprecated /** - * Represents a notebook. Notebooks are composed of cells and metadata. + * @deprecated use notebooks instead */ - export interface NotebookDocument { + export const notebook: typeof notebooks; - /** - * The associated uri for this notebook. - * - * *Note* that most notebooks use the `file`-scheme, which means they are files on disk. However, **not** all notebooks are - * saved on disk and therefore the `scheme` must be checked before trying to access the underlying file or siblings on disk. - * - * @see [FileSystemProvider](#FileSystemProvider) - * @see [TextDocumentContentProvider](#TextDocumentContentProvider) - */ - readonly uri: Uri; - - // todo@API should we really expose this? - readonly viewType: string; - - /** - * The version number of this notebook (it will strictly increase after each - * change, including undo/redo). - */ - readonly version: number; - - /** - * `true` if there are unpersisted changes. - */ - readonly isDirty: boolean; - - /** - * Is this notebook representing an untitled file which has not been saved yet. - */ - readonly isUntitled: boolean; - - /** - * `true` if the notebook has been closed. A closed notebook isn't synchronized anymore - * and won't be re-used when the same resource is opened again. - */ - readonly isClosed: boolean; - - /** - * The [metadata](#NotebookDocumentMetadata) for this notebook. - */ - readonly metadata: NotebookDocumentMetadata; - - /** - * The number of cells in the notebook. - */ - readonly cellCount: number; - - /** - * Return the cell at the specified index. The index will be adjusted to the notebook. - * - * @param index - The index of the cell to retrieve. - * @return A [cell](#NotebookCell). - */ - cellAt(index: number): NotebookCell; - - /** - * Get the cells of this notebook. A subset can be retrieved by providing - * a range. The range will be adjuset to the notebook. - * - * @param range A notebook range. - * @returns The cells contained by the range or all cells. - */ - getCells(range?: NotebookRange): NotebookCell[]; + //#endregion - /** - * Save the document. The saving will be handled by the corresponding content provider - * - * @return A promise that will resolve to true when the document - * has been saved. If the file was not dirty or the save failed, - * will return false. - */ - save(): Thenable; - } + //#region https://github.com/microsoft/vscode/issues/106744, NotebookEditor /** - * A notebook range represents on ordered pair of two cell indicies. - * It is guaranteed that start is less than or equal to end. + * Represents a notebook editor that is attached to a {@link NotebookDocument notebook}. */ - export class NotebookRange { - - /** - * The zero-based start index of this range. - */ - readonly start: number; - - /** - * The exclusive end index of this range (zero-based). - */ - readonly end: number; - - /** - * `true` if `start` and `end` are equals - */ - readonly isEmpty: boolean; - - /** - * Create a new notebook range. If `start` is not - * before or equal to `end`, the values will be swapped. - * - * @param start start index - * @param end end index. - */ - constructor(start: number, end: number); - - /** - * Derive a new range for this range. - * - * @param change An object that describes a change to this range. - * @return A range that reflects the given change. Will return `this` range if the change - * is not changing anything. - */ - with(change: { start?: number, end?: number }): NotebookRange; - } - export enum NotebookEditorRevealType { /** * The range will be revealed with as little scrolling as possible. */ Default = 0, + /** * The range will always be revealed in the center of the viewport. */ @@ -1211,10 +1096,14 @@ declare module 'vscode' { AtTop = 3 } + /** + * Represents a notebook editor that is attached to a {@link NotebookDocument notebook}. + */ export interface NotebookEditor { /** * The document associated with this notebook editor. */ + //todo@api rename to notebook? readonly document: NotebookDocument; /** @@ -1229,6 +1118,12 @@ declare module 'vscode' { */ readonly visibleRanges: NotebookRange[]; + /** + * Scroll as indicated by `revealType` in order to reveal the given range. + * + * @param range A range. + * @param revealType The scrolling strategy for revealing `range`. + */ revealRange(range: NotebookRange, revealType?: NotebookEditorRevealType): void; /** @@ -1238,6 +1133,10 @@ declare module 'vscode' { } export interface NotebookDocumentMetadataChangeEvent { + /** + * The {@link NotebookDocument notebook document} for which the document metadata have changed. + */ + //todo@API rename to notebook? readonly document: NotebookDocument; } @@ -1252,74 +1151,50 @@ declare module 'vscode' { } export interface NotebookCellsChangeEvent { - /** - * The affected document. + * The {@link NotebookDocument notebook document} for which the cells have changed. */ + //todo@API rename to notebook? readonly document: NotebookDocument; readonly changes: ReadonlyArray; } export interface NotebookCellOutputsChangeEvent { - /** - * The affected document. + * The {@link NotebookDocument notebook document} for which the cell outputs have changed. */ + //todo@API remove? use cell.notebook instead? readonly document: NotebookDocument; + // NotebookCellOutputsChangeEvent.cells vs NotebookCellMetadataChangeEvent.cell readonly cells: NotebookCell[]; } export interface NotebookCellMetadataChangeEvent { + /** + * The {@link NotebookDocument notebook document} for which the cell metadata have changed. + */ + //todo@API remove? use cell.notebook instead? readonly document: NotebookDocument; + // NotebookCellOutputsChangeEvent.cells vs NotebookCellMetadataChangeEvent.cell readonly cell: NotebookCell; } export interface NotebookEditorSelectionChangeEvent { + /** + * The {@link NotebookEditor notebook editor} for which the selections have changed. + */ readonly notebookEditor: NotebookEditor; readonly selections: ReadonlyArray } export interface NotebookEditorVisibleRangesChangeEvent { + /** + * The {@link NotebookEditor notebook editor} for which the visible ranges have changed. + */ readonly notebookEditor: NotebookEditor; readonly visibleRanges: ReadonlyArray; } - export interface NotebookCellExecutionStateChangeEvent { - readonly document: NotebookDocument; - readonly cell: NotebookCell; - readonly executionState: NotebookCellExecutionState; - } - - // todo@API support ids https://github.com/jupyter/enhancement-proposals/blob/master/62-cell-id/cell-id.md - export class NotebookCellData { - kind: NotebookCellKind; - // todo@API better names: value? text? - source: string; - // todo@API how does language and MD relate? - language: string; - outputs?: NotebookCellOutput[]; - metadata?: NotebookCellMetadata; - latestExecutionSummary?: NotebookCellExecutionSummary; - constructor(kind: NotebookCellKind, source: string, language: string, outputs?: NotebookCellOutput[], metadata?: NotebookCellMetadata, latestExecutionSummary?: NotebookCellExecutionSummary); - } - - export class NotebookData { - cells: NotebookCellData[]; - metadata: NotebookDocumentMetadata; - constructor(cells: NotebookCellData[], metadata?: NotebookDocumentMetadata); - } - - /** @deprecated used NotebookController */ - export interface NotebookCommunication { - /** @deprecated used NotebookController */ - readonly editorId: string; - /** @deprecated used NotebookController */ - readonly onDidReceiveMessage: Event; - /** @deprecated used NotebookController */ - postMessage(message: any): Thenable; - /** @deprecated used NotebookController */ - asWebviewUri(localResource: Uri): Uri; - } export interface NotebookDocumentShowOptions { viewColumn?: ViewColumn; @@ -1328,23 +1203,19 @@ declare module 'vscode' { selections?: NotebookRange[]; } - export namespace notebook { + export namespace notebooks { - export function openNotebookDocument(uri: Uri): Thenable; - export const onDidOpenNotebookDocument: Event; - export const onDidCloseNotebookDocument: Event; export const onDidSaveNotebookDocument: Event; - /** - * All currently known notebook documents. - */ - export const notebookDocuments: ReadonlyArray; export const onDidChangeNotebookDocumentMetadata: Event; export const onDidChangeNotebookCells: Event; + + // todo@API add onDidChangeNotebookCellOutputs export const onDidChangeCellOutputs: Event; + // todo@API add onDidChangeNotebookCellMetadata export const onDidChangeCellMetadata: Event; } @@ -1362,64 +1233,34 @@ declare module 'vscode' { //#endregion - //#region https://github.com/microsoft/vscode/issues/106744, NotebookCellOutput - - // code specific mime types - // application/x.notebook.error-traceback - // application/x.notebook.stdout - // application/x.notebook.stderr - // application/x.notebook.stream - export class NotebookCellOutputItem { - - // todo@API - // add factory functions for common mime types - // static textplain(value:string): NotebookCellOutputItem; - // static errortrace(value:any): NotebookCellOutputItem; - - readonly mime: string; - readonly value: unknown; - readonly metadata?: Record; - - constructor(mime: string, value: unknown, metadata?: Record); - } - - // @jrieken - // todo@API think about readonly... - //TODO@API add execution count to cell output? - export class NotebookCellOutput { - readonly id: string; - readonly outputs: NotebookCellOutputItem[]; - readonly metadata?: Record; + //#region https://github.com/microsoft/vscode/issues/106744, NotebookEditorEdit - constructor(outputs: NotebookCellOutputItem[], metadata?: Record); + // todo@API add NotebookEdit-type which handles all these cases? + // export class NotebookEdit { + // range: NotebookRange; + // newCells: NotebookCellData[]; + // newMetadata?: NotebookDocumentMetadata; + // constructor(range: NotebookRange, newCells: NotebookCellData) + // } - constructor(outputs: NotebookCellOutputItem[], id: string, metadata?: Record); - } + // export class NotebookCellEdit { + // newMetadata?: NotebookCellMetadata; + // } - //#endregion - - //#region https://github.com/microsoft/vscode/issues/106744, NotebookEditorEdit + // export interface WorkspaceEdit { + // set(uri: Uri, edits: TextEdit[] | NotebookEdit[]): void + // } export interface WorkspaceEdit { + // todo@API add NotebookEdit-type which handles all these cases? replaceNotebookMetadata(uri: Uri, value: NotebookDocumentMetadata): void; - - // todo@API use NotebookCellRange - replaceNotebookCells(uri: Uri, start: number, end: number, cells: NotebookCellData[], metadata?: WorkspaceEditEntryMetadata): void; + replaceNotebookCells(uri: Uri, range: NotebookRange, cells: NotebookCellData[], metadata?: WorkspaceEditEntryMetadata): void; replaceNotebookCellMetadata(uri: Uri, index: number, cellMetadata: NotebookCellMetadata, metadata?: WorkspaceEditEntryMetadata): void; - - replaceNotebookCellOutput(uri: Uri, index: number, outputs: NotebookCellOutput[], metadata?: WorkspaceEditEntryMetadata): void; - appendNotebookCellOutput(uri: Uri, index: number, outputs: NotebookCellOutput[], metadata?: WorkspaceEditEntryMetadata): void; - - // TODO@api - // https://jupyter-protocol.readthedocs.io/en/latest/messaging.html#update-display-data - replaceNotebookCellOutputItems(uri: Uri, index: number, outputId: string, items: NotebookCellOutputItem[], metadata?: WorkspaceEditEntryMetadata): void; - appendNotebookCellOutputItems(uri: Uri, index: number, outputId: string, items: NotebookCellOutputItem[], metadata?: WorkspaceEditEntryMetadata): void; } export interface NotebookEditorEdit { replaceMetadata(value: NotebookDocumentMetadata): void; replaceCells(start: number, end: number, cells: NotebookCellData[]): void; - replaceCellOutput(index: number, outputs: NotebookCellOutput[]): void; replaceCellMetadata(index: number, metadata: NotebookCellMetadata): void; } @@ -1427,11 +1268,11 @@ declare module 'vscode' { /** * Perform an edit on the notebook associated with this notebook editor. * - * The given callback-function is invoked with an [edit-builder](#NotebookEditorEdit) which must + * The given callback-function is invoked with an {@link NotebookEditorEdit edit-builder} which must * be used to make edits. Note that the edit-builder is only valid while the * callback executes. * - * @param callback A function which can create edits using an [edit-builder](#NotebookEditorEdit). + * @param callback A function which can create edits using an {@link NotebookEditorEdit edit-builder}. * @return A promise that resolves with a value indicating if the edits could be applied. */ // @jrieken REMOVE maybe @@ -1440,105 +1281,60 @@ declare module 'vscode' { //#endregion - //#region https://github.com/microsoft/vscode/issues/106744, NotebookSerializer - - export interface NotebookSerializer { - deserializeNotebook(data: Uint8Array, token: CancellationToken): NotebookData | Thenable; - serializeNotebook(data: NotebookData, token: CancellationToken): Uint8Array | Thenable; - } - - export namespace notebook { + //#region https://github.com/microsoft/vscode/issues/106744, NotebookEditorDecorationType - // todo@API remove output when notebook marks that as transient, same for metadata - export function registerNotebookSerializer(notebookType: string, provider: NotebookSerializer, options?: NotebookDocumentContentOptions): Disposable; + export interface NotebookEditor { + setDecorations(decorationType: NotebookEditorDecorationType, range: NotebookRange): void; } - //#endregion - - //#region https://github.com/microsoft/vscode/issues/119949 - - - export interface NotebookFilter { - readonly viewType?: string; - readonly scheme?: string; - readonly pattern?: GlobPattern; + export interface NotebookDecorationRenderOptions { + backgroundColor?: string | ThemeColor; + borderColor?: string | ThemeColor; + top: ThemableDecorationAttachmentRenderOptions; } - export type NotebookSelector = NotebookFilter | string | ReadonlyArray; - - export interface NotebookExecutionHandler { - /** - * @param cells The notebook cells to execute - * @param controller The controller that the handler is attached to - */ - (this: NotebookController, cells: NotebookCell[], controller: NotebookController): void + export interface NotebookEditorDecorationType { + readonly key: string; + dispose(): void; } - export interface NotebookInterruptHandler { - (this: NotebookController): void; + export namespace notebooks { + export function createNotebookEditorDecorationType(options: NotebookDecorationRenderOptions): NotebookEditorDecorationType; } - export interface NotebookController { - - readonly id: string; - - // select notebook of a type and/or by file-pattern - readonly selector: NotebookSelector; - - /** - * A kernel can apply to one or many notebook documents but a notebook has only one active - * kernel. This event fires whenever a notebook has been associated to a kernel or when - * that association has been removed. - */ - readonly onDidChangeNotebookAssociation: Event<{ notebook: NotebookDocument, selected: boolean }>; - - // UI properties (get/set) - label: string; - description?: string; - isPreferred?: boolean; - - supportedLanguages: string[]; - hasExecutionOrder?: boolean; - - /** - * The execute handler is invoked when the run gestures in the UI are selected, e.g Run Cell, Run All, - * Run Selection etc. - */ - executeHandler: NotebookExecutionHandler; + //#endregion - // optional kernel interrupt command - interruptHandler?: NotebookInterruptHandler - dispose(): void; + //#region https://github.com/microsoft/vscode/issues/106744, NotebookConcatTextDocument + export namespace notebooks { /** - * Manually create an execution task. This should only be used when cell execution - * has started before creating the kernel instance or when execution can be triggered - * from another source. + * Create a document that is the concatenation of all notebook cells. By default all code-cells are included + * but a selector can be provided to narrow to down the set of cells. * - * @param cell The notebook cell for which to create the execution - * @returns A notebook cell execution. + * @param notebook + * @param selector */ - createNotebookCellExecutionTask(cell: NotebookCell): NotebookCellExecutionTask; - - // ipc - readonly preloads: NotebookKernelPreload[]; - readonly onDidReceiveMessage: Event<{ editor: NotebookEditor, message: any }>; - postMessage(message: any, editor?: NotebookEditor): Thenable; - asWebviewUri(localResource: Uri): Uri; + // todo@API really needed? we didn't find a user here + export function createConcatTextDocument(notebook: NotebookDocument, selector?: DocumentSelector): NotebookConcatTextDocument; } - export namespace notebook { + export interface NotebookConcatTextDocument { + readonly uri: Uri; + readonly isClosed: boolean; + dispose(): void; + readonly onDidChange: Event; + readonly version: number; + getText(): string; + getText(range: Range): string; - /** - * Creates a new notebook controller. - * - * @param id Unique identifier of the controller - * @param selector A notebook selector to narrow down notebook type or path - * @param label The label of the controller - * @param handler - * @param preloads - */ - export function createNotebookController(id: string, selector: NotebookSelector, label: string, handler?: NotebookExecutionHandler, preloads?: NotebookKernelPreload[]): NotebookController; + offsetAt(position: Position): number; + positionAt(offset: number): Position; + validateRange(range: Range): Range; + validatePosition(position: Position): Position; + + locationAt(positionOrRange: Position | Range): Location; + positionAt(location: Location): Position; + contains(uri: Uri): boolean; } //#endregion @@ -1580,307 +1376,180 @@ declare module 'vscode' { readonly onDidChangeNotebookContentOptions?: Event; /** - * Content providers should always use [file system providers](#FileSystemProvider) to - * resolve the raw content for `uri` as the resouce is not necessarily a file on disk. - */ - openNotebook(uri: Uri, openContext: NotebookDocumentOpenContext, token: CancellationToken): NotebookData | Thenable; - - // todo@API use NotebookData instead - saveNotebook(document: NotebookDocument, token: CancellationToken): Thenable; - - // todo@API use NotebookData instead - saveNotebookAs(targetResource: Uri, document: NotebookDocument, token: CancellationToken): Thenable; - - // todo@API use NotebookData instead - backupNotebook(document: NotebookDocument, context: NotebookDocumentBackupContext, token: CancellationToken): Thenable; - } - - export namespace notebook { - - // TODO@api use NotebookDocumentFilter instead of just notebookType:string? - // TODO@API options duplicates the more powerful variant on NotebookContentProvider - export function registerNotebookContentProvider(notebookType: string, provider: NotebookContentProvider, options?: NotebookDocumentContentOptions): Disposable; - } - - //#endregion - - //#region https://github.com/microsoft/vscode/issues/106744, NotebookKernel - - export interface NotebookKernelPreload { - provides?: string | string[]; - uri: Uri; - } - - /** @deprecated used NotebookController */ - export interface NotebookKernel { - - // todo@API make this mandatory? - readonly id?: string; - - label: string; - description?: string; - detail?: string; - isPreferred?: boolean; - - // todo@API do we need an preload change event? - preloads?: NotebookKernelPreload[]; - - /** - * languages supported by kernel - * - first is preferred - * - `undefined` means all languages available in the editor - */ - supportedLanguages?: string[]; - - // todo@API kernel updating itself - // fired when properties like the supported languages etc change - // onDidChangeProperties?: Event - - /** - * A kernel can optionally implement this which will be called when any "cancel" button is clicked in the document. - */ - interrupt?(document: NotebookDocument): void; - - /** - * Called when the user triggers execution of a cell by clicking the run button for a cell, multiple cells, - * or full notebook. The cell will be put into the Pending state when this method is called. If - * createNotebookCellExecutionTask has not been called by the time the promise returned by this method is - * resolved, the cell will be put back into the Idle state. - */ - executeCellsRequest(document: NotebookDocument, ranges: NotebookRange[]): Thenable; - } - - export interface NotebookCellExecuteStartContext { - /** - * The time that execution began, in milliseconds in the Unix epoch. Used to drive the clock - * that shows for how long a cell has been running. If not given, the clock won't be shown. - */ - startTime?: number; - } - - export interface NotebookCellExecuteEndContext { - /** - * If true, a green check is shown on the cell status bar. - * If false, a red X is shown. - */ - success?: boolean; - - /** - * The time that execution finished, in milliseconds in the Unix epoch. - */ - endTime?: number; - } - - /** - * A NotebookCellExecutionTask is how the kernel modifies a notebook cell as it is executing. When - * [`createNotebookCellExecutionTask`](#notebook.createNotebookCellExecutionTask) is called, the cell - * enters the Pending state. When `start()` is called on the execution task, it enters the Executing state. When - * `end()` is called, it enters the Idle state. While in the Executing state, cell outputs can be - * modified with the methods on the run task. - * - * All outputs methods operate on this NotebookCellExecutionTask's cell by default. They optionally take - * a cellIndex parameter that allows them to modify the outputs of other cells. `appendOutputItems` and - * `replaceOutputItems` operate on the output with the given ID, which can be an output on any cell. They - * all resolve once the output edit has been applied. - */ - export interface NotebookCellExecutionTask { - readonly document: NotebookDocument; - readonly cell: NotebookCell; - - start(context?: NotebookCellExecuteStartContext): void; - executionOrder: number | undefined; - end(result?: NotebookCellExecuteEndContext): void; - readonly token: CancellationToken; - - clearOutput(cellIndex?: number): Thenable; - appendOutput(out: NotebookCellOutput | NotebookCellOutput[], cellIndex?: number): Thenable; - replaceOutput(out: NotebookCellOutput | NotebookCellOutput[], cellIndex?: number): Thenable; - appendOutputItems(items: NotebookCellOutputItem | NotebookCellOutputItem[], outputId: string): Thenable; - replaceOutputItems(items: NotebookCellOutputItem | NotebookCellOutputItem[], outputId: string): Thenable; - } - - export enum NotebookCellExecutionState { - Idle = 1, - Pending = 2, - Executing = 3, - } - - export namespace notebook { - /** - * Creates a [`NotebookCellExecutionTask`](#NotebookCellExecutionTask). Should only be called by a kernel. Returns undefined unless requested by the active kernel. - * @param uri The [uri](#Uri) of the notebook document. - * @param index The index of the cell. - * @param kernelId The id of the kernel requesting this run task. If this kernel is not the current active kernel, `undefined` is returned. + * Content providers should always use {@link FileSystemProvider file system providers} to + * resolve the raw content for `uri` as the resouce is not necessarily a file on disk. */ - export function createNotebookCellExecutionTask(uri: Uri, index: number, kernelId: string): NotebookCellExecutionTask | undefined; - - export const onDidChangeCellExecutionState: Event; - } + openNotebook(uri: Uri, openContext: NotebookDocumentOpenContext, token: CancellationToken): NotebookData | Thenable; - export type NotebookFilenamePattern = GlobPattern | { include: GlobPattern; exclude: GlobPattern; }; + // todo@API use NotebookData instead + saveNotebook(document: NotebookDocument, token: CancellationToken): Thenable; - // todo@API why not for NotebookContentProvider? - export interface NotebookDocumentFilter { - viewType?: string | string[]; - filenamePattern?: NotebookFilenamePattern; - } + // todo@API use NotebookData instead + saveNotebookAs(targetResource: Uri, document: NotebookDocument, token: CancellationToken): Thenable; - /** @deprecated used NotebookController */ - export interface NotebookKernelProvider { - onDidChangeKernels?: Event; - provideKernels(document: NotebookDocument, token: CancellationToken): ProviderResult; - resolveKernel?(kernel: T, document: NotebookDocument, webview: NotebookCommunication, token: CancellationToken): ProviderResult; + // todo@API use NotebookData instead + backupNotebook(document: NotebookDocument, context: NotebookDocumentBackupContext, token: CancellationToken): Thenable; } - export interface NotebookEditor { - /** @deprecated kernels are private object*/ - readonly kernel?: NotebookKernel; - } + export namespace notebooks { - export namespace notebook { - /** @deprecated */ - export const onDidChangeActiveNotebookKernel: Event<{ document: NotebookDocument, kernel: NotebookKernel | undefined; }>; - /** @deprecated used NotebookController */ - export function registerNotebookKernelProvider(selector: NotebookDocumentFilter, provider: NotebookKernelProvider): Disposable; + // TODO@api use NotebookDocumentFilter instead of just notebookType:string? + // TODO@API options duplicates the more powerful variant on NotebookContentProvider + export function registerNotebookContentProvider(notebookType: string, provider: NotebookContentProvider, options?: NotebookDocumentContentOptions): Disposable; } //#endregion - //#region https://github.com/microsoft/vscode/issues/106744, NotebookEditorDecorationType - - export interface NotebookEditor { - setDecorations(decorationType: NotebookEditorDecorationType, range: NotebookRange): void; - } - - export interface NotebookDecorationRenderOptions { - backgroundColor?: string | ThemeColor; - borderColor?: string | ThemeColor; - top: ThemableDecorationAttachmentRenderOptions; - } + //#region https://github.com/microsoft/vscode/issues/106744, LiveShare - export interface NotebookEditorDecorationType { - readonly key: string; - dispose(): void; + export interface NotebookRegistrationData { + displayName: string; + filenamePattern: (GlobPattern | { include: GlobPattern; exclude: GlobPattern; })[]; + exclusive?: boolean; } - export namespace notebook { - export function createNotebookEditorDecorationType(options: NotebookDecorationRenderOptions): NotebookEditorDecorationType; + export namespace notebooks { + // SPECIAL overload with NotebookRegistrationData + export function registerNotebookContentProvider(notebookType: string, provider: NotebookContentProvider, options?: NotebookDocumentContentOptions, registrationData?: NotebookRegistrationData): Disposable; + // SPECIAL overload with NotebookRegistrationData + export function registerNotebookSerializer(notebookType: string, serializer: NotebookSerializer, options?: NotebookDocumentContentOptions, registration?: NotebookRegistrationData): Disposable; } //#endregion - //#region https://github.com/microsoft/vscode/issues/106744, NotebookCellStatusBarItem - - /** - * Represents the alignment of status bar items. - */ - export enum NotebookCellStatusBarAlignment { + //#region https://github.com/microsoft/vscode/issues/39441 + export interface CompletionItem { /** - * Aligned to the left side. + * Will be merged into CompletionItem#label */ - Left = 1, + label2?: CompletionItemLabel; + } + export interface CompletionItemLabel { /** - * Aligned to the right side. + * The function or variable. Rendered leftmost. */ - Right = 2 - } - - export class NotebookCellStatusBarItem { - readonly text: string; - readonly alignment: NotebookCellStatusBarAlignment; - readonly command?: string | Command; - readonly tooltip?: string; - readonly priority?: number; - readonly accessibilityInformation?: AccessibilityInformation; - - constructor(text: string, alignment: NotebookCellStatusBarAlignment, command?: string | Command, tooltip?: string, priority?: number, accessibilityInformation?: AccessibilityInformation); - } + name: string; - interface NotebookCellStatusBarItemProvider { /** - * Implement and fire this event to signal that statusbar items have changed. The provide method will be called again. + * The parameters without the return type. Render after `name`. */ - onDidChangeCellStatusBarItems?: Event; + parameters?: string; /** - * The provider will be called when the cell scrolls into view, when its content, outputs, language, or metadata change, and when it changes execution state. + * The fully qualified name, like package name or file path. Rendered after `signature`. */ - provideCellStatusBarItems(cell: NotebookCell, token: CancellationToken): ProviderResult; - } + qualifier?: string; - export namespace notebook { - export function registerNotebookCellStatusBarItemProvider(selector: NotebookDocumentFilter, provider: NotebookCellStatusBarItemProvider): Disposable; + /** + * The return-type of a function or type of a property/variable. Rendered rightmost. + */ + type?: string; } //#endregion - //#region https://github.com/microsoft/vscode/issues/106744, NotebookConcatTextDocument + //#region @https://github.com/microsoft/vscode/issues/123601, notebook messaging - export namespace notebook { + export interface NotebookRendererMessage { /** - * Create a document that is the concatenation of all notebook cells. By default all code-cells are included - * but a selector can be provided to narrow to down the set of cells. - * - * @param notebook - * @param selector + * Editor that sent the message. */ - // @jrieken REMOVE. p_never - // todo@API really needed? we didn't find a user here - export function createConcatTextDocument(notebook: NotebookDocument, selector?: DocumentSelector): NotebookConcatTextDocument; - } + editor: NotebookEditor; - export interface NotebookConcatTextDocument { - uri: Uri; - isClosed: boolean; - dispose(): void; - onDidChange: Event; - version: number; - getText(): string; - getText(range: Range): string; + /** + * Message sent from the webview. + */ + message: T; + } - offsetAt(position: Position): number; - positionAt(offset: number): Position; - validateRange(range: Range): Range; - validatePosition(position: Position): Position; + /** + * Renderer messaging is used to communicate with a single renderer. It's + * returned from {@link notebook.createRendererMessaging}. + */ + export interface NotebookRendererMessaging { + /** + * Events that fires when a message is received from a renderer. + */ + onDidReceiveMessage: Event>; - locationAt(positionOrRange: Position | Range): Location; - positionAt(location: Location): Position; - contains(uri: Uri): boolean; + /** + * Sends a message to the renderer. + * @param editor Editor to target with the message + * @param message Message to send + */ + postMessage(editor: NotebookEditor, message: TSend): void; } - //#endregion - - //#region https://github.com/microsoft/vscode/issues/39441 + /** + * Represents a script that is loaded into the notebook renderer before rendering output. This allows + * to provide and share functionality for notebook markup and notebook output renderers. + */ + export class NotebookRendererScript { - export interface CompletionItem { /** - * Will be merged into CompletionItem#label + * APIs that the preload provides to the renderer. These are matched + * against the `dependencies` and `optionalDependencies` arrays in the + * notebook renderer contribution point. */ - label2?: CompletionItemLabel; - } + provides: string[]; - export interface CompletionItemLabel { /** - * The function or variable. Rendered leftmost. + * URI for the file to preload */ - name: string; + uri: Uri; /** - * The parameters without the return type. Render after `name`. + * @param uri URI for the file to preload + * @param provides Value for the `provides` property */ - parameters?: string; + constructor(uri: Uri, provides?: string | string[]); + } + + export interface NotebookController { + + // todo@API allow add, not remove + readonly rendererScripts: NotebookRendererScript[]; /** - * The fully qualified name, like package name or file path. Rendered after `signature`. + * An event that fires when a {@link NotebookController.rendererScripts renderer script} has send a message to + * the controller. */ - qualifier?: string; + readonly onDidReceiveMessage: Event<{ editor: NotebookEditor, message: any }>; /** - * The return-type of a function or type of a property/variable. Rendered rightmost. + * Send a message to the renderer of notebook editors. + * + * Note that only editors showing documents that are bound to this controller + * are receiving the message. + * + * @param message The message to send. + * @param editor A specific editor to send the message to. When `undefined` all applicable editors are receiving the message. + * @returns A promise that resolves to a boolean indicating if the message has been send or not. */ - type?: string; + postMessage(message: any, editor?: NotebookEditor): Thenable; + + //todo@API validate this works + asWebviewUri(localResource: Uri): Uri; + } + + export namespace notebooks { + + export function createNotebookController(id: string, viewType: string, label: string, handler?: NotebookExecuteHandler, rendererScripts?: NotebookRendererScript[]): NotebookController; + + /** + * Creates a new messaging instance used to communicate with a specific + * renderer. The renderer only has access to messaging if `requiresMessaging` + * is set in its contribution. + * + * @see https://github.com/microsoft/vscode/issues/123601 + * @param rendererId The renderer ID to communicate with + */ + // todo@API can ANY extension talk to renderer or is there a check that the calling extension + // declared the renderer in its package.json? + // todo@API align with vscode.Webview -> remove generics + export function createRendererMessaging(rendererId: string): NotebookRendererMessaging; } //#endregion @@ -1906,7 +1575,7 @@ declare module 'vscode' { id?: string; /** - * The icon path or [ThemeIcon](#ThemeIcon) for the timeline item. + * The icon path or {@link ThemeIcon} for the timeline item. */ iconPath?: Uri | { light: Uri; dark: Uri; } | ThemeIcon; @@ -1921,7 +1590,7 @@ declare module 'vscode' { detail?: string; /** - * The [command](#Command) that should be executed when the timeline item is selected. + * The {@link Command} that should be executed when the timeline item is selected. */ command?: Command; @@ -1959,7 +1628,7 @@ declare module 'vscode' { export interface TimelineChangeEvent { /** - * The [uri](#Uri) of the resource for which the timeline changed. + * The {@link Uri} of the resource for which the timeline changed. */ uri: Uri; @@ -1979,7 +1648,7 @@ declare module 'vscode' { }; /** - * An array of [timeline items](#TimelineItem). + * An array of {@link TimelineItem timeline items}. */ readonly items: readonly TimelineItem[]; } @@ -2015,12 +1684,12 @@ declare module 'vscode' { readonly label: string; /** - * Provide [timeline items](#TimelineItem) for a [Uri](#Uri). + * Provide {@link TimelineItem timeline items} for a {@link Uri}. * - * @param uri The [uri](#Uri) of the file to provide the timeline for. + * @param uri The {@link Uri} of the file to provide the timeline for. * @param options A set of options to determine how results should be returned. * @param token A cancellation token. - * @return The [timeline result](#TimelineResult) or a thenable that resolves to such. The lack of a result + * @return The {@link TimelineResult timeline result} or a thenable that resolves to such. The lack of a result * can be signaled by returning `undefined`, `null`, or an empty array. */ provideTimeline(uri: Uri, options: TimelineOptions, token: CancellationToken): ProviderResult; @@ -2036,7 +1705,7 @@ declare module 'vscode' { * * @param scheme A scheme or schemes that defines which documents this provider is applicable to. Can be `*` to target all documents. * @param provider A timeline provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ export function registerTimelineProvider(scheme: string | string[], provider: TimelineProvider): Disposable; } @@ -2065,49 +1734,49 @@ declare module 'vscode' { //#region https://github.com/microsoft/vscode/issues/16221 - // todo@API rename to InlayHint + // todo@API Split between Inlay- and OverlayHints (InlayHint are for a position, OverlayHints for a non-empty range) // todo@API add "mini-markdown" for links and styles - // todo@API remove description - // (done:) add InlayHintKind with type, argument, etc + // (done) remove description + // (done) rename to InlayHint + // (done) add InlayHintKind with type, argument, etc export namespace languages { /** - * Register a inline hints provider. + * Register a inlay hints provider. * * Multiple providers can be registered for a language. In that case providers are asked in * parallel and the results are merged. A failing provider (rejected promise or exception) will * not cause a failure of the whole operation. * * @param selector A selector that defines the documents this provider is applicable to. - * @param provider An inline hints provider. - * @return A [disposable](#Disposable) that unregisters this provider when being disposed. + * @param provider An inlay hints provider. + * @return A {@link Disposable} that unregisters this provider when being disposed. */ - export function registerInlineHintsProvider(selector: DocumentSelector, provider: InlineHintsProvider): Disposable; + export function registerInlayHintsProvider(selector: DocumentSelector, provider: InlayHintsProvider): Disposable; } - export enum InlineHintKind { + export enum InlayHintKind { Other = 0, Type = 1, Parameter = 2, } /** - * Inline hint information. + * Inlay hint information. */ - export class InlineHint { + export class InlayHint { /** * The text of the hint. */ text: string; /** - * The range of the hint. + * The position of this hint. */ - range: Range; - - kind?: InlineHintKind; - - // todo@API remove this - description?: string | MarkdownString; + position: Position; + /** + * The kind of this hint. + */ + kind?: InlayHintKind; /** * Whitespace before the hint. */ @@ -2118,29 +1787,29 @@ declare module 'vscode' { whitespaceAfter?: boolean; // todo@API make range first argument - constructor(text: string, range: Range, kind?: InlineHintKind); + constructor(text: string, position: Position, kind?: InlayHintKind); } /** - * The inline hints provider interface defines the contract between extensions and - * the inline hints feature. + * The inlay hints provider interface defines the contract between extensions and + * the inlay hints feature. */ - export interface InlineHintsProvider { + export interface InlayHintsProvider { /** - * An optional event to signal that inline hints have changed. - * @see [EventEmitter](#EventEmitter) + * An optional event to signal that inlay hints have changed. + * @see {@link EventEmitter} */ - onDidChangeInlineHints?: Event; + onDidChangeInlayHints?: Event; /** + * * @param model The document in which the command was invoked. - * @param range The range for which line hints should be computed. + * @param range The range for which inlay hints should be computed. * @param token A cancellation token. - * - * @return A list of arguments labels or a thenable that resolves to such. + * @return A list of inlay hints or a thenable that resolves to such. */ - provideInlineHints(model: TextDocument, range: Range, token: CancellationToken): ProviderResult; + provideInlayHints(model: TextDocument, range: Range, token: CancellationToken): ProviderResult; } //#endregion @@ -2168,7 +1837,7 @@ declare module 'vscode' { export interface TextDocument { /** - * The [notebook](#NotebookDocument) that contains this document as a notebook cell or `undefined` when + * The {@link NotebookDocument notebook} that contains this document as a notebook cell or `undefined` when * the document is not contained by a notebook (this should be the more frequent case). */ notebook: NotebookDocument | undefined; @@ -2203,7 +1872,7 @@ declare module 'vscode' { export function createDocumentTestObserver(document: TextDocument): TestObserver; /** - * Creates a {@link TestRunTask}. This should be called by the + * Creates a {@link TestRun}. This should be called by the * {@link TestRunner} when a request is made to execute tests, and may also * be called if a test run is detected externally. Once created, tests * that are included in the results will be moved into the @@ -2218,7 +1887,7 @@ declare module 'vscode' { * persisted in VS Code. This may be false if the results are coming from * a file already saved externally, such as a coverage information file. */ - export function createTestRunTask(request: TestRunRequest, name?: string, persist?: boolean): TestRunTask; + export function createTestRun(request: TestRunRequest, name?: string, persist?: boolean): TestRun; /** * Creates a new managed {@link TestItem} instance. @@ -2339,7 +2008,7 @@ declare module 'vscode' { /** * Starts a test run. When called, the controller should call - * {@link vscode.test.createTestRunTask}. All tasks associated with the + * {@link vscode.test.createTestRun}. All tasks associated with the * run should be created before the function returns or the reutrned * promise is resolved. * @@ -2376,7 +2045,7 @@ declare module 'vscode' { /** * Options given to {@link TestController.runTests} */ - export interface TestRunTask { + export interface TestRun { /** * The human-readable name of the run. This can be used to * disambiguate multiple sets of results in a test run. It is useful if @@ -2453,7 +2122,7 @@ declare module 'vscode' { /** * URI this TestItem is associated with. May be a file or directory. */ - uri: Uri; + uri?: Uri; /** * Display name describing the test item. @@ -2476,7 +2145,7 @@ declare module 'vscode' { /** * URI this TestItem is associated with. May be a file or directory. */ - readonly uri: Uri; + readonly uri?: Uri; /** * A mapping of children by ID to the associated TestItem instances. @@ -2708,7 +2377,7 @@ declare module 'vscode' { /** * URI this TestItem is associated with. May be a file or file. */ - readonly uri: Uri; + readonly uri?: Uri; /** * Display name describing the test case. @@ -2917,12 +2586,76 @@ declare module 'vscode' { //#endregion + //#region @joaomoreno https://github.com/microsoft/vscode/issues/124263 + // This API change only affects behavior and documentation, not API surface. + + namespace env { + + /** + * Resolves a uri to form that is accessible externally. + * + * #### `http:` or `https:` scheme + * + * Resolves an *external* uri, such as a `http:` or `https:` link, from where the extension is running to a + * uri to the same resource on the client machine. + * + * This is a no-op if the extension is running on the client machine. + * + * If the extension is running remotely, this function automatically establishes a port forwarding tunnel + * from the local machine to `target` on the remote and returns a local uri to the tunnel. The lifetime of + * the port forwarding tunnel is managed by VS Code and the tunnel can be closed by the user. + * + * *Note* that uris passed through `openExternal` are automatically resolved and you should not call `asExternalUri` on them. + * + * #### `vscode.env.uriScheme` + * + * Creates a uri that - if opened in a browser (e.g. via `openExternal`) - will result in a registered {@link UriHandler} + * to trigger. + * + * Extensions should not make any assumptions about the resulting uri and should not alter it in anyway. + * Rather, extensions can e.g. use this uri in an authentication flow, by adding the uri as callback query + * argument to the server to authenticate to. + * + * *Note* that if the server decides to add additional query parameters to the uri (e.g. a token or secret), it + * will appear in the uri that is passed to the {@link UriHandler}. + * + * **Example** of an authentication flow: + * ```typescript + * vscode.window.registerUriHandler({ + * handleUri(uri: vscode.Uri): vscode.ProviderResult { + * if (uri.path === '/did-authenticate') { + * console.log(uri.toString()); + * } + * } + * }); + * + * const callableUri = await vscode.env.asExternalUri(vscode.Uri.parse(`${vscode.env.uriScheme}://my.extension/did-authenticate`)); + * await vscode.env.openExternal(callableUri); + * ``` + * + * *Note* that extensions should not cache the result of `asExternalUri` as the resolved uri may become invalid due to + * a system or user action — for example, in remote cases, a user may close a port forwarding tunnel that was opened by + * `asExternalUri`. + * + * #### Any other scheme + * + * Any other scheme will be handled as if the provided URI is a workspace URI. In that case, the method will return + * a URI which, when handled, will make VS Code open the workspace. + * + * @return A uri that can be used on the client machine. + */ + export function asExternalUri(target: Uri): Thenable; + } + + //#endregion + //#region https://github.com/Microsoft/vscode/issues/15178 // TODO@API must be a class export interface OpenEditorInfo { name: string; resource: Uri; + isActive: boolean; } export namespace window { @@ -2940,53 +2673,20 @@ declare module 'vscode' { */ export interface WorkspaceTrustRequestOptions { /** - * When true, a modal dialog will be used to request workspace trust. - * When false, a badge will be displayed on the settings gear activity bar item. + * Custom message describing the user action that requires workspace + * trust. If omitted, a generic message will be displayed in the workspace + * trust request dialog. */ - readonly modal: boolean; + readonly message?: string; } export namespace workspace { - /** - * When true, the user has explicitly trusted the contents of the workspace. - */ - export const isTrusted: boolean; - /** * Prompt the user to chose whether to trust the current workspace * @param options Optional object describing the properties of the - * workspace trust request. Defaults to { modal: false } - * When using a non-modal request, the promise will return immediately. - * Any time trust is not given, it is recommended to use the - * `onDidReceiveWorkspaceTrust` event to listen for trust changes. + * workspace trust request. */ - export function requestWorkspaceTrust(options?: WorkspaceTrustRequestOptions): Thenable; - - /** - * Event that fires when the current workspace has been trusted. - */ - export const onDidReceiveWorkspaceTrust: Event; - } - - //#endregion - - //#region https://github.com/microsoft/vscode/issues/115807 - - export interface Webview { - /** - * @param message A json serializable message to send to the webview. - * - * For older versions of vscode, if an `ArrayBuffer` is included in `message`, - * it will not be serialized properly and will not be received by the webview. - * Similarly any TypedArrays, such as a `Uint8Array`, will be very inefficiently - * serialized and will also not be recreated as a typed array inside the webview. - * - * However if your extension targets vscode 1.56+ in the `engines` field of its - * `package.json` any `ArrayBuffer` values that appear in `message` will be more - * efficiently transferred to the webview and will also be recreated inside of - * the webview. - */ - postMessage(message: any): Thenable; + export function requestWorkspaceTrust(options?: WorkspaceTrustRequestOptions): Thenable; } //#endregion @@ -3000,9 +2700,23 @@ declare module 'vscode' { Ignore = 5 } - export interface PortAttributes { + export class PortAttributes { + /** + * The port number associated with this this set of attributes. + */ port: number; - autoForwardAction: PortAutoForwardAction + + /** + * The action to be taken when this port is detected for auto forwarding. + */ + autoForwardAction: PortAutoForwardAction; + + /** + * Creates a new PortAttributes object + * @param port the port number + * @param autoForwardAction the action to take when this port is detected + */ + constructor(port: number, autoForwardAction: PortAutoForwardAction); } export interface PortAttributesProvider { @@ -3031,7 +2745,7 @@ declare module 'vscode' { } //#endregion - // region https://github.com/microsoft/vscode/issues/119904 @eamodio + //#region https://github.com/microsoft/vscode/issues/119904 @eamodio export interface SourceControlInputBox { @@ -3042,4 +2756,132 @@ declare module 'vscode' { } //#endregion + + //#region https://github.com/microsoft/vscode/issues/124024 @hediet @alexdima + + export namespace languages { + export function registerInlineCompletionItemProvider(selector: DocumentSelector, provider: InlineCompletionItemProvider): Disposable; + } + + export interface InlineCompletionItemProvider { + provideInlineCompletionItems(document: TextDocument, position: Position, context: InlineCompletionContext, token: CancellationToken): ProviderResult>; + } + + export interface InlineCompletionContext { + /** + * How the completion was triggered. + */ + readonly triggerKind: InlineCompletionTriggerKind; + } + + /** + * How an {@link InlineCompletionItemProvider inline completion provider} was triggered. + */ + export enum InlineCompletionTriggerKind { + /** + * Completion was triggered automatically while editing. + * It is sufficient to return a single completion item in this case. + */ + Automatic = 0, + + /** + * Completion was triggered explicitly by a user gesture. + * Return multiple completion items to enable cycling through them. + */ + Explicit = 1, + } + + export class InlineCompletionList { + items: T[]; + + constructor(items: T[]); + } + + export class InlineCompletionItem { + /** + * The text to insert. + * If the text contains a line break, the range must end at the end of a line. + * If existing text should be replaced, the existing text must be a prefix of the text to insert. + */ + text: string; + + /** + * The range to replace. + * Must begin and end on the same line. + */ + range?: Range; + + /** + * An optional {@link Command} that is executed *after* inserting this completion. + */ + command?: Command; + + constructor(text: string, range?: Range, command?: Command); + } + + + /** + * Be aware that this API will not ever be finalized. + */ + export namespace window { + export function getInlineCompletionItemController(provider: InlineCompletionItemProvider): InlineCompletionController; + } + + /** + * Be aware that this API will not ever be finalized. + */ + export interface InlineCompletionController { + // eslint-disable-next-line vscode-dts-event-naming + readonly onDidShowCompletionItem: Event>; + } + + /** + * Be aware that this API will not ever be finalized. + */ + export interface InlineCompletionItemDidShowEvent { + completionItem: T; + } + + //#endregion + + //#region FileSystemProvider stat readonly - https://github.com/microsoft/vscode/issues/73122 + + export enum FilePermission { + /** + * The file is readonly. + * + * *Note:* All `FileStat` from a `FileSystemProvider` that is registered with + * the option `isReadonly: true` will be implicitly handled as if `FilePermission.Readonly` + * is set. As a consequence, it is not possible to have a readonly file system provider + * registered where some `FileStat` are not readonly. + */ + Readonly = 1 + } + + /** + * The `FileStat`-type represents metadata about a file + */ + export interface FileStat { + + /** + * The permissions of the file, e.g. whether the file is readonly. + * + * *Note:* This value might be a bitmask, e.g. `FilePermission.Readonly | FilePermission.Other`. + */ + permissions?: FilePermission; + } + + //#endregion + + //#region https://github.com/microsoft/vscode/issues/87110 @eamodio + + export interface Memento { + + /** + * The stored keys. + */ + readonly keys: readonly string[]; + } + + //#endregion } diff --git a/src/ui/debugTerminalUI.ts b/src/ui/debugTerminalUI.ts index b711a11e4..356decd7a 100644 --- a/src/ui/debugTerminalUI.ts +++ b/src/ui/debugTerminalUI.ts @@ -15,6 +15,7 @@ import { readConfig, registerCommand, } from '../common/contributionUtils'; +import { EventEmitter } from '../common/events'; import { ProxyLogger } from '../common/logging/proxyLogger'; import { applyDefaults, @@ -97,7 +98,7 @@ export const launchVirtualTerminalParent = ( return; } - if (!(await vscode.workspace.requestWorkspaceTrust({ modal: true }))) { + if (!(await vscode.workspace.requestWorkspaceTrust())) { target.detach(); return; } @@ -180,6 +181,22 @@ async function getWorkspaceFolder() { return picked?.folder ?? Abort; } +class ProfileTerminalLauncher extends TerminalNodeLauncher { + private optionsReadyEmitter = new EventEmitter(); + public readonly onOptionsReady = this.optionsReadyEmitter.event; + + /** @override */ + protected createTerminal(options: vscode.TerminalOptions) { + this.optionsReadyEmitter.fire(options); + return new Promise(resolve => { + const listener = vscode.window.onDidOpenTerminal(t => { + listener.dispose(); + resolve(t); + }); + }); + } +} + /** * Registers a command to launch the debugger terminal. */ @@ -194,6 +211,15 @@ export function registerDebugTerminalUI( { launcher: TerminalNodeLauncher; folder?: vscode.WorkspaceFolder; cwd?: string } >(); + const createLauncher = (logger: ProxyLogger, binary: NodeBinaryProvider) => + new TerminalNodeLauncher( + binary, + logger, + services.get(FS), + services.get(NodeOnlyPathResolverFactory), + services.get(IPortLeaseTracker), + ); + /** * See docblocks on {@link DelegateLauncher} for more information on * how this works. @@ -203,6 +229,7 @@ export function registerDebugTerminalUI( command?: string, workspaceFolder?: vscode.WorkspaceFolder, defaultConfig?: Partial, + createLauncherFn = createLauncher, ) { if (!workspaceFolder) { const picked = await getWorkspaceFolder(); @@ -229,12 +256,9 @@ export function registerDebugTerminalUI( } const logger = new ProxyLogger(); - const launcher = new TerminalNodeLauncher( - new NodeBinaryProvider(logger, services.get(FS), noPackageJsonProvider), + const launcher = createLauncherFn( logger, - services.get(FS), - services.get(NodeOnlyPathResolverFactory), - services.get(IPortLeaseTracker), + new NodeBinaryProvider(logger, services.get(FS), noPackageJsonProvider), ); launcher.onTerminalCreated(terminal => { @@ -260,6 +284,24 @@ export function registerDebugTerminalUI( registerCommand(vscode.commands, Commands.CreateDebuggerTerminal, (command, folder, config) => launchTerminal(delegateFactory, command, folder, config), ), + vscode.window.registerTerminalProfileProvider('extension.js-debug.debugTerminal', { + provideProfileOptions: () => + new Promise(resolve => + launchTerminal(delegateFactory, undefined, undefined, undefined, (logger, binary) => { + const launcher = new ProfileTerminalLauncher( + binary, + logger, + services.get(FS), + services.get(NodeOnlyPathResolverFactory), + services.get(IPortLeaseTracker), + ); + + launcher.onOptionsReady(resolve); + + return launcher; + }), + ), + }), vscode.window.registerTerminalLinkProvider?.(linkHandler), ); }