diff --git a/src/vscode-dts/vscode.d.ts b/src/vscode-dts/vscode.d.ts index 30ba7df267a..5266ffe9717 100644 --- a/src/vscode-dts/vscode.d.ts +++ b/src/vscode-dts/vscode.d.ts @@ -10063,7 +10063,7 @@ declare module 'vscode' { } /** - * A panel that contains a webview. + * A panel that contains a {@linkcode Webview}. */ export interface WebviewPanel { /** @@ -10115,7 +10115,7 @@ declare module 'vscode' { /** * Fired when the panel is disposed. * - * This may be because the user closed the panel or because `.dispose()` was + * This may be because the user closed the panel or because {@linkcode WebviewPanel.dispose dispose} was * called on it. * * Trying to use the panel after it has been disposed throws an exception. @@ -10128,7 +10128,7 @@ declare module 'vscode' { * A webview panel may only show in a single column at a time. If it is already showing, this * method moves it to a new column. * - * @param viewColumn View column to show the panel in. Shows in the current `viewColumn` if undefined. + * @param viewColumn View column to show the panel in. Shows in the current {@linkcode WebviewPanel.viewColumn} if undefined. * @param preserveFocus When `true`, the webview will not take focus. */ reveal(viewColumn?: ViewColumn, preserveFocus?: boolean): void; @@ -10138,17 +10138,17 @@ declare module 'vscode' { * * This closes the panel if it showing and disposes of the resources owned by the webview. * Webview panels are also disposed when the user closes the webview panel. Both cases - * fire the `onDidDispose` event. + * fire the {@linkcode onDidDispose} event. */ dispose(): any; } /** - * Event fired when a webview panel's view state changes. + * Event fired when a {@linkcode WebviewPanel webview panel's} view state changes. */ export interface WebviewPanelOnDidChangeViewStateEvent { /** - * Webview panel whose view state changed. + * {@linkcode WebviewPanel} whose view state changed. */ readonly webviewPanel: WebviewPanel; } @@ -10283,12 +10283,12 @@ declare module 'vscode' { * * To save resources, the editor normally deallocates webview documents (the iframe content) that are not visible. * For example, when the user collapse a view or switches to another top level activity in the sidebar, the - * `WebviewView` itself is kept alive but the webview's underlying document is deallocated. It is recreated when + * {@linkcode WebviewView} itself is kept alive but the webview's underlying document is deallocated. It is recreated when * the view becomes visible again. * - * You can prevent this behavior by setting `retainContextWhenHidden` in the `WebviewOptions`. However this - * increases resource usage and should be avoided wherever possible. Instead, you can use persisted state to - * save off a webview's state so that it can be quickly recreated as needed. + * You can prevent this behavior by setting {@linkcode WebviewOptions.retainContextWhenHidden retainContextWhenHidden} in the {@linkcode WebviewOptions}. + * However this increases resource usage and should be avoided wherever possible. Instead, you can use + * persisted state to save off a webview's state so that it can be quickly recreated as needed. * * To save off a persisted state, inside the webview call `acquireVsCodeApi().setState()` with * any json serializable object. To restore the state again, call `getState()`. For example: @@ -10311,7 +10311,7 @@ declare module 'vscode' { } /** - * Provider for creating `WebviewView` elements. + * Provider for creating {@linkcode WebviewView} elements. */ export interface WebviewViewProvider { /** @@ -10335,7 +10335,7 @@ declare module 'vscode' { * * Text based custom editors use a {@linkcode TextDocument} as their data model. This considerably simplifies * implementing a custom editor as it allows the editor to handle many common operations such as - * undo and backup. The provider is responsible for synchronizing text changes between the webview and the `TextDocument`. + * undo and backup. The provider is responsible for synchronizing text changes between the webview and the {@linkcode TextDocument}. */ export interface CustomTextEditorProvider { @@ -10345,13 +10345,12 @@ declare module 'vscode' { * This is called when a user first opens a resource for a `CustomTextEditorProvider`, or if they reopen an * existing editor using this `CustomTextEditorProvider`. * - * * @param document Document for the resource to resolve. * * @param webviewPanel The webview panel used to display the editor UI for this resource. * * 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 + * the event listeners on it that it is interested in. The provider can also hold onto the {@linkcode WebviewPanel} to * use later for example in a command. See {@linkcode WebviewPanel} for additional details. * * @param token A cancellation token that indicates the result is no longer needed. @@ -10399,7 +10398,7 @@ declare module 'vscode' { * * This is invoked by the editor when the user undoes this edit. To implement `undo`, your * extension should restore the document and editor to the state they were in just before this - * edit was added to the editor's internal edit stack by `onDidChangeCustomDocument`. + * edit was added to the editor's internal edit stack by {@linkcode CustomEditorProvider.onDidChangeCustomDocument}. */ undo(): Thenable | void; @@ -10408,7 +10407,7 @@ declare module 'vscode' { * * This is invoked by the editor when the user redoes this edit. To implement `redo`, your * extension should restore the document and editor to the state they were in just after this - * edit was added to the editor's internal edit stack by `onDidChangeCustomDocument`. + * edit was added to the editor's internal edit stack by {@linkcode CustomEditorProvider.onDidChangeCustomDocument}. */ redo(): Thenable | void; @@ -10440,7 +10439,7 @@ declare module 'vscode' { /** * Unique identifier for the backup. * - * This id is passed back to your extension in `openCustomDocument` when opening a custom editor from a backup. + * This id is passed back to your extension in {@linkcode CustomReadonlyEditorProvider.openCustomDocument openCustomDocument} when opening a custom editor from a backup. */ readonly id: string; @@ -10505,10 +10504,10 @@ declare module 'vscode' { * Create a new document for a given resource. * * `openCustomDocument` is called when the first time an editor for a given resource is opened. The opened - * document is then passed to `resolveCustomEditor` so that the editor can be shown to the user. + * document is then passed to {@link resolveCustomEditor} so that the editor can be shown to the user. * - * Already opened `CustomDocument` are re-used if the user opened additional editors. When all editors for a - * given resource are closed, the `CustomDocument` is disposed of. Opening an editor at this point will + * Already opened {@linkcode CustomDocument CustomDocuments} are re-used if the user opened additional editors. When all editors for a + * given resource are closed, the {@linkcode CustomDocument CustomDocuments} is disposed of. Opening an editor at this point will * trigger another call to `openCustomDocument`. * * @param uri Uri of the document to open. @@ -10558,18 +10557,18 @@ declare module 'vscode' { * anything from changing some text, to cropping an image, to reordering a list. Your extension is free to * define what an edit is and what data is stored on each edit. * - * Firing `onDidChange` causes the editors to be marked as being dirty. This is cleared when the user either - * saves or reverts the file. + * Firing {@linkcode CustomEditorProvider.onDidChangeCustomDocument onDidChangeCustomDocument} causes the + * editors to be marked as being dirty. This is cleared when the user either saves or reverts the file. * - * Editors that support undo/redo must fire a `CustomDocumentEditEvent` whenever an edit happens. This allows + * Editors that support undo/redo must fire a {@linkcode CustomDocumentEditEvent} whenever an edit happens. This allows * users to undo and redo the edit using the editor's standard keyboard shortcuts. The editor will also mark * the editor as no longer being dirty if the user undoes all edits to the last saved state. * - * Editors that support editing but cannot use the editor's standard undo/redo mechanism must fire a `CustomDocumentContentChangeEvent`. + * Editors that support editing but cannot use the editor's standard undo/redo mechanism must fire a {@linkcode CustomDocumentContentChangeEvent}. * The only way for a user to clear the dirty state of an editor that does not support undo/redo is to either * `save` or `revert` the file. * - * An editor should only ever fire `CustomDocumentEditEvent` events, or only ever fire `CustomDocumentContentChangeEvent` events. + * An editor should only ever fire {@linkcode CustomDocumentEditEvent} events, or only ever fire {@linkcode CustomDocumentContentChangeEvent} events. */ readonly onDidChangeCustomDocument: Event> | Event>; @@ -10579,14 +10578,14 @@ declare module 'vscode' { * This method is invoked by the editor when the user saves a custom editor. This can happen when the user * triggers save while the custom editor is active, by commands such as `save all`, or by auto save if enabled. * - * To implement `save`, the implementer must persist the custom editor. This usually means writing the - * file data for the custom document to disk. After `save` completes, any associated editor instances will - * no longer be marked as dirty. + * The implementer must persist the custom editor. This usually means writing the + * file data for the custom document to disk. After {@linkcode saveCustomDocument} completes, any associated + * editor instances will no longer be marked as dirty. * * @param document Document to save. * @param cancellation Token that signals the save is no longer required (for example, if another save was triggered). * - * @returns Thenable signaling that saving has completed. + * @returns A {@linkcode Thenable} that saving has completed. */ saveCustomDocument(document: T, cancellation: CancellationToken): Thenable; @@ -10594,7 +10593,7 @@ declare module 'vscode' { * Save a custom document to a different location. * * This method is invoked by the editor when the user triggers 'save as' on a custom editor. The implementer must - * persist the custom editor to `destination`. + * persist the custom editor to {@linkcode destination}. * * When the user accepts save as, the current editor is be replaced by an non-dirty editor for the newly saved file. * @@ -10602,7 +10601,7 @@ declare module 'vscode' { * @param destination Location to save to. * @param cancellation Token that signals the save is no longer required. * - * @returns Thenable signaling that saving has completed. + * @returns A {@linkcode Thenable} signaling that saving has completed. */ saveCustomDocumentAs(document: T, destination: Uri, cancellation: CancellationToken): Thenable; @@ -10612,30 +10611,30 @@ declare module 'vscode' { * This method is invoked by the editor when the user triggers `File: Revert File` in a custom editor. (Note that * this is only used using the editor's `File: Revert File` command and not on a `git revert` of the file). * - * To implement `revert`, the implementer must make sure all editor instances (webviews) for `document` + * The implementer must make sure all editor instances (webviews) for {@linkcode document} * are displaying the document in the same state is saved in. This usually means reloading the file from the * workspace. * * @param document Document to revert. * @param cancellation Token that signals the revert is no longer required. * - * @returns Thenable signaling that the change has completed. + * @returns A {@linkcode Thenable} signaling that the revert has completed. */ revertCustomDocument(document: T, cancellation: CancellationToken): Thenable; /** * Back up a dirty custom document. * - * Backups are used for hot exit and to prevent data loss. Your `backup` method should persist the resource in + * Backups are used for hot exit and to prevent data loss. Your {@linkcode backupCustomDocument} method should persist the resource in * its current state, i.e. with the edits applied. Most commonly this means saving the resource to disk in * the `ExtensionContext.storagePath`. When the editor reloads and your custom editor is opened for a resource, * your extension should first check to see if any backups exist for the resource. If there is a backup, your * extension should load the file contents from there instead of from the resource in the workspace. * - * `backup` is triggered approximately one second after the user stops editing the document. If the user - * rapidly edits the document, `backup` will not be invoked until the editing stops. + * {@linkcode backupCustomDocument} is triggered approximately one second after the user stops editing the document. If the user + * rapidly edits the document, {@linkcode backupCustomDocument} will not be invoked until the editing stops. * - * `backup` is not invoked when `auto save` is enabled (since auto save already persists the resource). + * {@linkcode backupCustomDocument} is not invoked when `auto save` is enabled (since auto save already persists the resource). * * @param document Document to backup. * @param context Information that can be used to backup the document. @@ -10643,6 +10642,8 @@ declare module 'vscode' { * extension to decided how to respond to cancellation. If for example your extension is backing up a large file * in an operation that takes time to complete, your extension may decide to finish the ongoing backup rather * than cancelling it to ensure that the editor has some valid backup. + * + * @returns A {@linkcode Thenable} signaling that the backup has completed. */ backupCustomDocument(document: T, context: CustomDocumentBackupContext, cancellation: CancellationToken): Thenable; }