Mirrors/vscode
1
0
Fork 0
mirror of https://github.com/microsoft/vscode.git synced 2025-12-28 06:31:58 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Add a prompt to update doc comments, use it to improve Quick Pick/Input documentation (#275935)

Browse Source 
* Add a prompt to update doc comments, use it to improve Quick Pick/Input documentation

* Update .github/prompts/doc-comments.prompt.md

Co-authored-by: Joaquín Ruales <1588988+jruales@users.noreply.github.com>

* Update .github/prompts/doc-comments.prompt.md

Co-authored-by: Joaquín Ruales <1588988+jruales@users.noreply.github.com>

* Add max line length and 'cleanup' mode.

* Add linting rule

---------

Co-authored-by: Joaquín Ruales <1588988+jruales@users.noreply.github.com>
This commit is contained in:
Dmitriy Vasyura 2025-11-07 02:14:02 -08:00 committed by GitHub
parent 4049fa9a33
commit 331be293ce
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
7 changed files with 231 additions and 166 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
.github/prompts/doc-comments.prompt.md vendored Normal file
View File

@ -0,0 +1,30 @@
---
agent: agent
description: 'Update doc comments'
tools: ['edit', 'search', 'new', 'runCommands', 'runTasks', 'usages', 'vscodeAPI', 'problems', 'changes', 'testFailure', 'openSimpleBrowser', 'fetch', 'githubRepo', 'extensions', 'todos', 'runTests']
---
# Role
You are an expert technical documentation editor specializing in public API documentation.
## Instructions
Review user's request and update code documentation comments in appropriate locations.
## Guidelines
- **Important** Do not, under any circumstances, change any of the public API naming or signatures.
- **Important** Fetch and review relevant code context (i.e. implementation source code) before making changes or adding comments.
- **Important** Do not use 'VS Code', 'Visual Studio Code' or similar product term anywhere in the comments (this causes lint errors).
- Follow American English grammar, orthography, and punctuation.
- Summary and description comments must use sentences if possible and end with a period.
- Use {@link \<symbol\>} where possible **and reasonable** to refer to code symbols.
- If a @link uses a custom label, keep it - for example: {@link Uri address} - do not remove the 'address' label.
- Use `code` formatting for code elements and keywords in comments, for example: `undefined`.
- Limit the maximum line length of comments to 120 characters.
## Cleanup Mode
If the user instructed you to "clean up" doc comments (e.g. by passing in "cleanup" as their prompt),
it is **very important** that you limit your changes to only fixing grammar, punctuation, formatting, and spelling mistakes.
**YOU MUST NOT** add new or remove or expand existing comments in cleanup mode.

309
src/vscode-dts/vscode.d.ts vendored
View File

@ -1872,89 +1872,105 @@ declare module 'vscode' {
}
/**
* The kind of {@link QuickPickItem quick pick item}.
* Defines the kind of {@link QuickPickItem quick pick item}.
*/
export enum QuickPickItemKind {
/**
* When a {@link QuickPickItem} has a kind of {@link Separator}, the item is just a visual separator and does not represent a real item.
* The only property that applies is {@link QuickPickItem.label label }. All other properties on {@link QuickPickItem} will be ignored and have no effect.
* A separator item that provides a visual grouping.
*
* When a {@link QuickPickItem} has a kind of {@link Separator}, the item is just a visual separator
* and does not represent a selectable item. The only property that applies is
* {@link QuickPickItem.label label}. All other properties on {@link QuickPickItem} will be ignored
* and have no effect.
*/
Separator = -1,
/**
* The default {@link QuickPickItem.kind} is an item that can be selected in the quick pick.
* The default kind for an item that can be selected in the quick pick.
*/
Default = 0,
}
/**
* Represents an item that can be selected from
* a list of items.
* Represents an item that can be selected from a list of items.
*/
export interface QuickPickItem {
/**
* A human-readable string which is rendered prominent. Supports rendering of {@link ThemeIcon theme icons} via
* the `$(<name>)`-syntax.
* A human-readable string which is rendered prominently.
*
* Note: When {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Default} (so a regular item
* instead of a separator), it supports rendering of {@link ThemeIcon theme icons} via the `$(<name>)`-syntax.
* Supports rendering of {@link ThemeIcon theme icons} via the `$(<name>)`-syntax.
*
* **Note:** When {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Default} (so a regular
* item instead of a separator), it supports rendering of {@link ThemeIcon theme icons} via the
* `$(<name>)`-syntax.
*/
label: string;
/**
* The kind of QuickPickItem that will determine how this item is rendered in the quick pick. When not specified,
* the default is {@link QuickPickItemKind.Default}.
* The kind of this item that determines how it is rendered in the quick pick.
*
* When not specified, the default is {@link QuickPickItemKind.Default}.
*/
kind?: QuickPickItemKind;
/**
* The icon path or {@link ThemeIcon} for the QuickPickItem.
* The icon for the item.
*/
iconPath?: IconPath;
/**
* A human-readable string which is rendered less prominent in the same line. Supports rendering of
* {@link ThemeIcon theme icons} via the `$(<name>)`-syntax.
* A human-readable string which is rendered less prominently in the same line.
*
* Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator}
* Supports rendering of {@link ThemeIcon theme icons} via the `$(<name>)`-syntax.
*
* **Note:** This property is ignored when {@link QuickPickItem.kind kind} is set to
* {@link QuickPickItemKind.Separator}.
*/
description?: string;
/**
* A human-readable string which is rendered less prominent in a separate line. Supports rendering of
* {@link ThemeIcon theme icons} via the `$(<name>)`-syntax.
* A human-readable string which is rendered less prominently in a separate line.
*
* Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator}
* Supports rendering of {@link ThemeIcon theme icons} via the `$(<name>)`-syntax.
*
* **Note:** This property is ignored when {@link QuickPickItem.kind kind} is set to
* {@link QuickPickItemKind.Separator}.
*/
detail?: string;
/**
* Optional flag indicating if this item is picked initially. This is only honored when using
* the {@link window.showQuickPick showQuickPick()} API. To do the same thing with
* the {@link window.createQuickPick createQuickPick()} API, simply set the {@link QuickPick.selectedItems}
* to the items you want picked initially.
* (*Note:* This is only honored when the picker allows multiple selections.)
* Optional flag indicating if this item is initially selected.
*
* This is only honored when using the {@link window.showQuickPick showQuickPick} API. To do the same
* thing with the {@link window.createQuickPick createQuickPick} API, simply set the
* {@link QuickPick.selectedItems selectedItems} to the items you want selected initially.
*
* **Note:** This is only honored when the picker allows multiple selections.
*
* @see {@link QuickPickOptions.canPickMany}
*
* Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator}
* **Note:** This property is ignored when {@link QuickPickItem.kind kind} is set to
* {@link QuickPickItemKind.Separator}.
*/
picked?: boolean;
/**
* Always show this item.
* Determines if this item is always shown, even when filtered out by the user's input.
*
* Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator}
* **Note:** This property is ignored when {@link QuickPickItem.kind kind} is set to
* {@link QuickPickItemKind.Separator}.
*/
alwaysShow?: boolean;
/**
* Optional buttons that will be rendered on this particular item. These buttons will trigger
* an {@link QuickPickItemButtonEvent} when clicked. Buttons are only rendered when using a quickpick
* created by the {@link window.createQuickPick createQuickPick()} API. Buttons are not rendered when using
* the {@link window.showQuickPick showQuickPick()} API.
* Optional buttons that will be rendered on this particular item.
*
* Note: this property is ignored when {@link QuickPickItem.kind kind} is set to {@link QuickPickItemKind.Separator}
* These buttons will trigger an {@link QuickPickItemButtonEvent} when pressed. Buttons are only rendered
* when using a quick pick created by the {@link window.createQuickPick createQuickPick} API. Buttons are
* not rendered when using the {@link window.showQuickPick showQuickPick} API.
*
* **Note:** This property is ignored when {@link QuickPickItem.kind kind} is set to
* {@link QuickPickItemKind.Separator}.
*/
buttons?: readonly QuickInputButton[];
}
@ -1965,33 +1981,33 @@ declare module 'vscode' {
export interface QuickPickOptions {
/**
* An optional string that represents the title of the quick pick.
* An optional title for the quick pick.
*/
title?: string;
/**
* An optional flag to include the description when filtering the picks.
* Determines if the {@link QuickPickItem.description description} should be included when filtering items. Defaults to `false`.
*/
matchOnDescription?: boolean;
/**
* An optional flag to include the detail when filtering the picks.
* Determines if the {@link QuickPickItem.detail detail} should be included when filtering items. Defaults to `false`.
*/
matchOnDetail?: boolean;
/**
* An optional string to show as placeholder in the input box to guide the user what to pick on.
* An optional string to show as placeholder in the input box to guide the user.
*/
placeHolder?: string;
/**
* Set to `true` to keep the picker open when focus moves to another part of the editor or to another window.
* This setting is ignored on iPad and is always false.
* This setting is ignored on iPad and is always `false`.
*/
ignoreFocusOut?: boolean;
/**
* An optional flag to make the picker accept multiple selections, if true the result is an array of picks.
* Determines if the picker allows multiple selections. When `true`, the result is an array of picks.
*/
canPickMany?: boolean;
@ -2002,24 +2018,24 @@ declare module 'vscode' {
}
/**
* Options to configure the behaviour of the {@link WorkspaceFolder workspace folder} pick UI.
* Options to configure the behavior of the {@link WorkspaceFolder workspace folder} pick UI.
*/
export interface WorkspaceFolderPickOptions {
/**
* An optional string to show as placeholder in the input box to guide the user what to pick on.
* An optional string to show as placeholder in the input box to guide the user.
*/
placeHolder?: string;
/**
* Set to `true` to keep the picker open when focus moves to another part of the editor or to another window.
* This setting is ignored on iPad and is always false.
* This setting is ignored on iPad and is always `false`.
*/
ignoreFocusOut?: boolean;
}
/**
* Options to configure the behaviour of a file open dialog.
* Options to configure the behavior of a file open dialog.
*
* * Note 1: On Windows and Linux, a file dialog cannot be both a file selector and a folder selector, so if you
* set both `canSelectFiles` and `canSelectFolders` to `true` on these platforms, a folder selector will be shown.
@ -2155,39 +2171,38 @@ declare module 'vscode' {
}
/**
* Impacts the behavior and appearance of the validation message.
*/
/**
* The severity level for input box validation.
* Severity levels for input box validation messages.
*/
export enum InputBoxValidationSeverity {
/**
* Informational severity level.
* Indicates an informational message that does not prevent input acceptance.
*/
Info = 1,
/**
* Warning severity level.
* Indicates a warning message that does not prevent input acceptance.
*/
Warning = 2,
/**
* Error severity level.
* Indicates an error message that prevents the user from accepting the input.
*/
Error = 3
}
/**
* Object to configure the behavior of the validation message.
* Represents a validation message for an {@link InputBox}.
*/
export interface InputBoxValidationMessage {
/**
* The validation message to display.
* The validation message to display to the user.
*/
readonly message: string;
/**
* The severity of the validation message.
* NOTE: When using `InputBoxValidationSeverity.Error`, the user will not be allowed to accept (hit ENTER) the input.
* `Info` and `Warning` will still allow the InputBox to accept the input.
* The severity level of the validation message.
*
* **Note:** When using {@link InputBoxValidationSeverity.Error}, the user will not be able to accept
* the input (e.g., by pressing Enter). {@link InputBoxValidationSeverity.Info Info} and
* {@link InputBoxValidationSeverity.Warning Warning} severities will still allow the input to be accepted.
*/
readonly severity: InputBoxValidationSeverity;
}
@ -11608,7 +11623,7 @@ declare module 'vscode' {
* @param items An array of strings, or a promise that resolves to an array of strings.
* @param options Configures the behavior of the selection list.
* @param token A token that can be used to signal cancellation.
* @returns A promise that resolves to the selected items or `undefined`.
* @returns A thenable that resolves to the selected items or `undefined`.
*/
export function showQuickPick(items: readonly string[] | Thenable<readonly string[]>, options: QuickPickOptions & { /** literal-type defines return type */canPickMany: true }, token?: CancellationToken): Thenable<string[] | undefined>;
@ -11618,7 +11633,7 @@ declare module 'vscode' {
* @param items An array of strings, or a promise that resolves to an array of strings.
* @param options Configures the behavior of the selection list.
* @param token A token that can be used to signal cancellation.
* @returns A promise that resolves to the selection or `undefined`.
* @returns A thenable that resolves to the selected string or `undefined`.
*/
export function showQuickPick(items: readonly string[] | Thenable<readonly string[]>, options?: QuickPickOptions, token?: CancellationToken): Thenable<string | undefined>;
@ -11628,7 +11643,7 @@ declare module 'vscode' {
* @param items An array of items, or a promise that resolves to an array of items.
* @param options Configures the behavior of the selection list.
* @param token A token that can be used to signal cancellation.
* @returns A promise that resolves to the selected items or `undefined`.
* @returns A thenable that resolves to the selected items or `undefined`.
*/
export function showQuickPick<T extends QuickPickItem>(items: readonly T[] | Thenable<readonly T[]>, options: QuickPickOptions & { /** literal-type defines return type */ canPickMany: true }, token?: CancellationToken): Thenable<T[] | undefined>;
@ -11638,7 +11653,7 @@ declare module 'vscode' {
* @param items An array of items, or a promise that resolves to an array of items.
* @param options Configures the behavior of the selection list.
* @param token A token that can be used to signal cancellation.
* @returns A promise that resolves to the selected item or `undefined`.
* @returns A thenable that resolves to the selected item or `undefined`.
*/
export function showQuickPick<T extends QuickPickItem>(items: readonly T[] | Thenable<readonly T[]>, options?: QuickPickOptions, token?: CancellationToken): Thenable<T | undefined>;
@ -11672,23 +11687,22 @@ declare module 'vscode' {
/**
* Opens an input box to ask the user for input.
*
* The returned value will be `undefined` if the input box was canceled (e.g. pressing ESC). Otherwise the
* The returned value will be `undefined` if the input box was canceled (e.g., pressing ESC). Otherwise the
* returned value will be the string typed by the user or an empty string if the user did not type
* anything but dismissed the input box with OK.
*
* @param options Configures the behavior of the input box.
* @param token A token that can be used to signal cancellation.
* @returns A promise that resolves to a string the user provided or to `undefined` in case of dismissal.
* @returns A thenable that resolves to a string the user provided or to `undefined` in case of dismissal.
*/
export function showInputBox(options?: InputBoxOptions, token?: CancellationToken): Thenable<string | undefined>;
/**
* Creates a {@link QuickPick} to let the user pick an item from a list
* of items of type T.
* 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 {@link window.showQuickPick}
* is easier to use. {@link window.createQuickPick} should be used
* when {@link 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.
*
* @returns A new {@link QuickPick}.
*/
@ -11697,9 +11711,9 @@ declare module 'vscode' {
/**
* Creates a {@link InputBox} to let the user enter some text input.
*
* 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.
* 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.
*
* @returns A new {@link InputBox}.
*/
@ -13279,115 +13293,115 @@ 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 {@link QuickInput.show}.
* The base interface for all quick input types.
*
* There are several reasons why this UI might have to be hidden and
* 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.)
* Quick input provides a unified way for extensions to interact with users through simple UI elements.
* A quick input UI is initially not visible. After configuring it through its properties the extension
* can make it visible by calling {@link QuickInput.show show}.
*
* 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 {@link QuickInput.hide}.
* There are several reasons why this UI might have to be hidden and the extension will be notified
* through {@link QuickInput.onDidHide onDidHide}. Examples include: an explicit call to
* {@link QuickInput.hide hide}, the user pressing Esc, some other input UI opening, etc.
*
* When the extension no longer needs this input UI, it should
* {@link QuickInput.dispose} it to allow for freeing up
* any resources associated with it.
* 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 {@link QuickInput.hide hide}.
*
* When the extension no longer needs this input UI, it should {@link QuickInput.dispose dispose} it
* to allow for freeing up any resources associated with it.
*
* See {@link QuickPick} and {@link InputBox} for concrete UIs.
*/
export interface QuickInput {
/**
* An optional title.
* An optional title for the input UI.
*/
title: string | undefined;
/**
* An optional current step count.
* An optional current step count for multi-step input flows.
*/
step: number | undefined;
/**
* An optional total step count.
* An optional total step count for multi-step input flows.
*/
totalSteps: number | undefined;
/**
* If the UI should allow for user input. Defaults to true.
* Determines if the UI should allow for user input. Defaults to `true`.
*
* Change this to false, e.g., while validating user input or
* loading data for the next step in user input.
* Change this to `false`, for example, while validating user input or loading data for the next
* step in user input.
*/
enabled: boolean;
/**
* If the UI should show a progress indicator. Defaults to false.
* Determines if the UI should show a progress indicator. Defaults to `false`.
*
* Change this to true, e.g., while loading more data or validating
* user input.
* Change this to `true`, for example, while loading more data or validating user input.
*/
busy: boolean;
/**
* If the UI should stay open even when loosing UI focus. Defaults to false.
* This setting is ignored on iPad and is always false.
* Determines if the UI should stay open even when losing UI focus. Defaults to `false`.
* This setting is ignored on iPad and is always `false`.
*/
ignoreFocusOut: boolean;
/**
* Makes the input UI visible in its current configuration. Any other input
* UI will first fire an {@link QuickInput.onDidHide} event.
* Makes the input UI visible in its current configuration.
*
* Any other input UI will first fire an {@link QuickInput.onDidHide onDidHide} event.
*/
show(): void;
/**
* Hides this input UI. This will also fire an {@link QuickInput.onDidHide}
* event.
* Hides this input UI.
*
* This will also fire an {@link QuickInput.onDidHide onDidHide} event.
*/
hide(): void;
/**
* 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 {@link QuickInput.onDidHide}.
* (Examples include: an explicit call to {@link QuickInput.hide},
* the user pressing Esc, some other input UI opening, etc.)
* There are several reasons why this UI might have to be hidden and the extension will be notified
* through {@link QuickInput.onDidHide onDidHide}. Examples include: an explicit call to
* {@link QuickInput.hide hide}, the user pressing Esc, some other input UI opening, etc.
*/
readonly onDidHide: Event<void>;
/**
* Dispose of this input UI and any associated resources. If it is still
* visible, it is first hidden. After this call the input UI is no longer
* functional and no additional methods or properties on it should be
* accessed. Instead a new input UI should be created.
* Dispose of this input UI and any associated resources.
*
* If it is still visible, it is first hidden. After this call the input UI is no longer functional
* and no additional methods or properties on it should be accessed. Instead a new input UI should
* be created.
*/
dispose(): void;
}
/**
* 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 {@link QuickPick.canSelectMany canSelectMany} to allow for
* selecting multiple items.
* A concrete {@link QuickInput} to let the user pick an item from a list of items of type `T`.
*
* 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.
* The items can be filtered through a filter text field and there is an option
* {@link QuickPick.canSelectMany canSelectMany} to allow for selecting multiple items.
*
* 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<T extends QuickPickItem> extends QuickInput {
/**
* Current value of the filter text.
* The current value of the filter text.
*/
value: string;
/**
* Optional placeholder shown in the filter textbox when no filter has been entered.
* Optional placeholder text displayed in the filter text box when no value has been entered.
*/
placeholder: string | undefined;
@ -13407,14 +13421,17 @@ declare module 'vscode' {
buttons: readonly QuickInputButton[];
/**
* An event signaling when a top level button (buttons stored in {@link buttons}) was triggered.
* This event does not fire for buttons on a {@link QuickPickItem}.
* An event signaling when a button was triggered.
*
* This event fires for buttons stored in the {@link QuickPick.buttons buttons} array. This event does
* not fire for buttons on a {@link QuickPickItem}.
*/
readonly onDidTriggerButton: Event<QuickInputButton>;
/**
* An event signaling when a button in a particular {@link QuickPickItem} was triggered.
* This event does not fire for buttons in the title bar.
*
* This event does not fire for buttons in the title bar which are part of {@link QuickPick.buttons buttons}.
*/
readonly onDidTriggerItemButton: Event<QuickPickItemButtonEvent<T>>;
@ -13424,22 +13441,22 @@ declare module 'vscode' {
items: readonly T[];
/**
* If multiple items can be selected at the same time. Defaults to false.
* Determines if multiple items can be selected at the same time. Defaults to `false`.
*/
canSelectMany: boolean;
/**
* If the filter text should also be matched against the description of the items. Defaults to false.
* Determines if the filter text should also be matched against the {@link QuickPickItem.description description} of the items. Defaults to `false`.
*/
matchOnDescription: boolean;
/**
* If the filter text should also be matched against the detail of the items. Defaults to false.
* Determines if the filter text should also be matched against the {@link QuickPickItem.detail detail} of the items. Defaults to `false`.
*/
matchOnDetail: boolean;
/**
* An optional flag to maintain the scroll position of the quick pick when the quick pick items are updated. Defaults to false.
* Determines if the scroll position is maintained when the quick pick items are updated. Defaults to `false`.
*/
keepScrollPosition?: boolean;
@ -13467,35 +13484,36 @@ declare module 'vscode' {
/**
* A concrete {@link QuickInput} to let the user input a text value.
*
* 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.
* 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 {
/**
* Current input value.
* The current input value.
*/
value: string;
/**
* Selection range in the input 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
* pre-filled value will be selected, when empty (start equals end) only the cursor will be set,
* otherwise the defined range will be selected.
* Selection range in the input value.
*
* This property does not get updated when the user types or makes a selection,
* but it can be updated by the extension.
* Defined as tuple of two numbers where the first is the inclusive start index and the second the
* exclusive end index. When `undefined` the whole pre-filled value will be selected, when empty
* (start equals end) only the cursor will be set, otherwise the defined range will be selected.
*
* This property does not get updated when the user types or makes a selection, but it can be updated
* by the extension.
*/
valueSelection: readonly [number, number] | undefined;
/**
* Optional placeholder shown when no value has been input.
* Optional placeholder text shown when no value has been input.
*/
placeholder: string | undefined;
/**
* If the input value should be hidden. Defaults to false.
* Determines if the input value should be hidden. Defaults to `false`.
*/
password: boolean;
@ -13526,23 +13544,24 @@ declare module 'vscode' {
/**
* An optional validation message indicating a problem with the current input value.
* By returning a string, the InputBox will use a default {@link InputBoxValidationSeverity} of Error.
* Returning undefined clears the validation message.
*
* By setting a string, the InputBox will use a default {@link InputBoxValidationSeverity} of Error.
* Returning `undefined` clears the validation message.
*/
validationMessage: string | InputBoxValidationMessage | undefined;
}
/**
* Button for an action in a {@link QuickPick} or {@link InputBox}.
* A button for an action in a {@link QuickPick} or {@link InputBox}.
*/
export interface QuickInputButton {
/**
* Icon for the button.
* The icon for the button.
*/
readonly iconPath: IconPath;
/**
* An optional tooltip.
* An optional tooltip displayed when hovering over the button.
*/
readonly tooltip?: string | undefined;
}
@ -13551,12 +13570,11 @@ declare module 'vscode' {
* Predefined buttons for {@link QuickPick} and {@link InputBox}.
*/
export class QuickInputButtons {
/**
* A back button for {@link QuickPick} and {@link InputBox}.
* A predefined 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.
* This button should be used for consistency when a navigation back button is needed. It comes
* with a predefined icon, tooltip, and location.
*/
static readonly Back: QuickInputButton;
@ -13567,12 +13585,11 @@ declare module 'vscode' {
}
/**
* An event signaling when a button in a particular {@link QuickPickItem} was triggered.
* This event does not fire for buttons in the title bar.
* An event describing a button that was pressed on a {@link QuickPickItem}.
*/
export interface QuickPickItemButtonEvent<T extends QuickPickItem> {
/**
* The button that was clicked.
* The button that was pressed.
*/
readonly button: QuickInputButton;
/**

25
src/vscode-dts/vscode.proposed.quickInputButtonLocation.d.ts vendored
View File

@ -7,35 +7,42 @@ declare module 'vscode' {
// https://github.com/microsoft/vscode/issues/175662
/**
* Specifies the location where a {@link QuickInputButton} should be rendered.
*/
export enum QuickInputButtonLocation {
/**
* In the title bar.
* The button is rendered in the title bar.
*/
Title = 1,
/**
* To the right of the input box.
* The button is rendered inline to the right of the input box.
*/
Inline = 2,
/**
* At the far end inside the input box.
* The button is rendered at the far end inside the input box.
*/
Input = 3
}
export interface QuickInputButton {
/**
* Where the button should be rendered. The default is {@link QuickInputButtonLocation.Title}.
* @note This property is ignored if the button was added to a QuickPickItem.
* The location where the button should be rendered.
*
* Defaults to {@link QuickInputButtonLocation.Title}.
*
* **Note:** This property is ignored if the button was added to a {@link QuickPickItem}.
*/
location?: QuickInputButtonLocation;
/**
* When present, indicates that the button is a toggle that can be checked.
* @note This property is currently only applicable to buttons with location {@link QuickInputButtonLocation.Input}.
* It must be set for such buttons and the state will be updated when the button is toggled.
* It cannot be set for buttons with other location value currently.
* When present, indicates that the button is a toggle button that can be checked or unchecked.
*
* **Note:** This property is currently only applicable to buttons with {@link QuickInputButtonLocation.Input} location.
* It must be set for such buttons, and the state will be updated when the button is toggled.
* It cannot be set for buttons with other location values.
*/
readonly toggle?: { checked: boolean };
}

11
src/vscode-dts/vscode.proposed.quickPickItemResource.d.ts vendored
View File

@ -9,12 +9,13 @@ declare module 'vscode' {
export interface QuickPickItem {
/**
* The {@link Uri} of the resource representing this item.
* A {@link Uri} representing the resource associated with this item.
*
* Will be used to derive the {@link label}, when it is not provided (falsy or empty).
* Will be used to derive the {@link description}, when it is not provided (falsy or empty).
* Will be used to derive the icon from current file icon theme, when {@link iconPath} has either
* {@link ThemeIcon.File} or {@link ThemeIcon.Folder} value.
* When set, this property is used to automatically derive several item properties if they are not explicitly provided:
* - **Label**: Derived from the resource's file name when {@link QuickPickItem.label label} is not provided or is empty.
* - **Description**: Derived from the resource's path when {@link QuickPickItem.description description} is not provided or is empty.
* - **Icon**: Derived from the current file icon theme when {@link QuickPickItem.iconPath iconPath} is set to
* {@link ThemeIcon.File} or {@link ThemeIcon.Folder}.
*/
resourceUri?: Uri;
}

5
src/vscode-dts/vscode.proposed.quickPickItemTooltip.d.ts vendored
View File

@ -9,7 +9,10 @@ declare module 'vscode' {
export interface QuickPickItem {
/**
* A tooltip that is rendered when hovering over the item.
* An optional tooltip that is displayed when hovering over this item.
*
* When specified, this tooltip takes precedence over the default hover behavior which shows
* the {@link QuickPickItem.description description}.
*/
tooltip?: string | MarkdownString;
}

10
src/vscode-dts/vscode.proposed.quickPickPrompt.d.ts vendored
View File

@ -9,16 +9,18 @@ declare module 'vscode' {
export interface QuickPick<T extends QuickPickItem> extends QuickInput {
/**
* An optional prompt text providing some ask or explanation to the user.
* Shown below the input box and above the quick pick items.
* Optional text that provides instructions or context to the user.
*
* The prompt is displayed below the input box and above the list of items.
*/
prompt: string | undefined;
}
export interface QuickPickOptions {
/**
* An optional prompt text providing some ask or explanation to the user.
* Shown below the input box and above the quick pick items.
* Optional text that provides instructions or context to the user.
*
* The prompt is displayed below the input box and above the list of items.
*/
prompt?: string;
}

7
src/vscode-dts/vscode.proposed.quickPickSortByLabel.d.ts vendored
View File

@ -9,7 +9,12 @@ declare module 'vscode' {
export interface QuickPick<T extends QuickPickItem> extends QuickInput {
/**
* An optional flag to sort the final results by index of first query match in label. Defaults to true.
* Controls whether items should be sorted based on the match position in their labels when filtering.
*
* When `true`, items are sorted by the position of the first match in the label, with items that
* match earlier in the label appearing first. When `false`, items maintain their original order.
*
* Defaults to `true`.
*/
// @API is a bug that we need this API at all. why do we change the sort order
// when extensions give us a (sorted) array of items?