diff --git a/.github/prompts/doc-comments.prompt.md b/.github/prompts/doc-comments.prompt.md new file mode 100644 index 00000000000..b3848435901 --- /dev/null +++ b/.github/prompts/doc-comments.prompt.md @@ -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 \} 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. diff --git a/src/vscode-dts/vscode.d.ts b/src/vscode-dts/vscode.d.ts index 8f20c5ea011..947b3e2568d 100644 --- a/src/vscode-dts/vscode.d.ts +++ b/src/vscode-dts/vscode.d.ts @@ -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 `$()`-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 `$()`-syntax. + * Supports rendering of {@link ThemeIcon theme icons} via the `$()`-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 + * `$()`-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 `$()`-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 `$()`-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 `$()`-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 `$()`-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, options: QuickPickOptions & { /** literal-type defines return type */canPickMany: true }, token?: CancellationToken): Thenable; @@ -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, options?: QuickPickOptions, token?: CancellationToken): Thenable; @@ -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(items: readonly T[] | Thenable, options: QuickPickOptions & { /** literal-type defines return type */ canPickMany: true }, token?: CancellationToken): Thenable; @@ -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(items: readonly T[] | Thenable, options?: QuickPickOptions, token?: CancellationToken): Thenable; @@ -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; /** - * 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; /** - * 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 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; /** * 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>; @@ -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 { /** - * The button that was clicked. + * The button that was pressed. */ readonly button: QuickInputButton; /** diff --git a/src/vscode-dts/vscode.proposed.quickInputButtonLocation.d.ts b/src/vscode-dts/vscode.proposed.quickInputButtonLocation.d.ts index bb41ac8a9ef..1f4e248548e 100644 --- a/src/vscode-dts/vscode.proposed.quickInputButtonLocation.d.ts +++ b/src/vscode-dts/vscode.proposed.quickInputButtonLocation.d.ts @@ -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 }; } diff --git a/src/vscode-dts/vscode.proposed.quickPickItemResource.d.ts b/src/vscode-dts/vscode.proposed.quickPickItemResource.d.ts index 0d54f87b6c6..dd763a23e56 100644 --- a/src/vscode-dts/vscode.proposed.quickPickItemResource.d.ts +++ b/src/vscode-dts/vscode.proposed.quickPickItemResource.d.ts @@ -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; } diff --git a/src/vscode-dts/vscode.proposed.quickPickItemTooltip.d.ts b/src/vscode-dts/vscode.proposed.quickPickItemTooltip.d.ts index ddf43ffd389..a0445cda13b 100644 --- a/src/vscode-dts/vscode.proposed.quickPickItemTooltip.d.ts +++ b/src/vscode-dts/vscode.proposed.quickPickItemTooltip.d.ts @@ -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; } diff --git a/src/vscode-dts/vscode.proposed.quickPickPrompt.d.ts b/src/vscode-dts/vscode.proposed.quickPickPrompt.d.ts index 52b04a34c83..2c37c8f71e0 100644 --- a/src/vscode-dts/vscode.proposed.quickPickPrompt.d.ts +++ b/src/vscode-dts/vscode.proposed.quickPickPrompt.d.ts @@ -9,16 +9,18 @@ declare module 'vscode' { export interface QuickPick 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; } diff --git a/src/vscode-dts/vscode.proposed.quickPickSortByLabel.d.ts b/src/vscode-dts/vscode.proposed.quickPickSortByLabel.d.ts index 01db687c22c..fb6557364a2 100644 --- a/src/vscode-dts/vscode.proposed.quickPickSortByLabel.d.ts +++ b/src/vscode-dts/vscode.proposed.quickPickSortByLabel.d.ts @@ -9,7 +9,12 @@ declare module 'vscode' { export interface QuickPick 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?