Merge branch 'main' of https://github.com/microsoft/vscode-docs into sync-public-docs

Author: ntrogh

api/extension-guides/language-model.md

@@ -73,7 +73,7 @@ Once you've built the prompt for the language model, you first select the langua
 
 To select the language model, you can specify the following properties: `vendor`, `id`, `family`, or `version`. Use these properties to either broadly match all models of a given vendor or family, or select one specific model by its ID. Learn more about these properties in the [API reference](/api/references/vscode-api#LanguageModelChat).
 
-> **Note**: Currently, `gpt-4o`, `gpt-4o-mini`, `o1-preview`, `o1-mini`, `claude-3.5-sonnet`, `gemini-1.5-pro` are supported for the language model family. If you are unsure what model to use, we recommend `gpt-4o` for it's performance and quality. For interactions directly in the editor, we recommend `gpt-4o-mini` for it's performance.
+> **Note**: Currently, `gpt-4o`, `gpt-4o-mini`, `o1`, `o1-mini`, `claude-3.5-sonnet` are supported for the language model family. If you are unsure what model to use, we recommend `gpt-4o` for it's performance and quality. For interactions directly in the editor, we recommend `gpt-4o-mini` for it's performance.
 
 If there are no models that match the specified criteria, the `selectChatModels` method returns an empty array. Your extension must appropriately handle this case.
 

api/language-extensions/images/language-server-extension-guide/lsp-illustration.png

@@ -9,7 +9,7 @@ MetaDescription: Visual Studio Code language extensions contribute programming l
 
 # Programmatic Language Features
 
-Programmatic Language Features is a set of smart-editing features powered by the [`vscode.languages.*`](/api/references/vscode-api#languages) API. There are two common ways to provide a dynamic language feature in Visual Studio Code. Let's take [Hover](#hover) as an example:
+Programmatic Language Features is a set of smart-editing features powered by the [`vscode.languages.*`](/api/references/vscode-api#languages) API. There are two common ways to provide a dynamic language feature in Visual Studio Code. Let's take [Hover](#show-hovers) as an example:
 
 ```ts
 vscode.languages.registerHoverProvider('javascript', {

api/language-extensions/programmatic-language-features.md

@@ -252,9 +252,12 @@ let success = await commands.executeCommand('vscode.openFolder', uri);
 * _context_ - An InlineValueContext
 * _(returns)_ - A promise that resolves to an array of InlineValue objects
 
-`vscode.open` - Opens the provided resource in the editor.
+`vscode.open` - Opens the provided resource in the editor. Can be a text or binary file, or an http(s) URL. If you need more control over the options for opening a text file, use `vscode.window.showTextDocument` instead.
 
-* _Uri_ -
+* _uri_ - Uri of a text or binary file, or an http(s) URL
+* _columnOrOptions_ - (optional) Either the column in which to open, or editor options, see `vscode.TextDocumentShowOptions`
+* _label_ - Editor label (optional)
+* _(returns)_ - no result
 
 `vscode.openWith` - Opens the provided resource with a specific editor.
 

api/references/commands.md

@@ -69,6 +69,26 @@ When needing to display progress for an indeterminate timeframe (for example, se
 
 *This example uses the progress notification to show the setup involved for a remote connection, while also providing a link to the output logs (**details**).*
 
+## Modal dialog
+
+When you need immediate user input for an action, you can opt to show a modal dialog. This UI element should be used with caution because a modal dialog blocks user interactions outside the dialog, until it's dismissed.
+
+![Modal dialog](images/examples/save-ai-generated-changes-dialog.png)
+
+*This dialog appears after moving a JavaScript/TypeScript file, asking to update import statements in other files.*
+
+**✔️ Do**
+
+* Only use modal dialogs if you need immediate user interaction
+* Where appropriate, provide an action to avoid repeated user confirmation (*Always*/*Never* action)
+* Consider using a checkbox to remember the user's choice
+
+**❌ Don't**
+
+* Use modal dialogs to confirm multiple steps
+* Use modal dialogs for showing messages that don't require an action from the user
+* Show a modal dialog for actions that are not explicitly initiated by the user
+
 ## Links
 
 * [Hello World extension sample](https://github.com/microsoft/vscode-extension-samples/tree/main/helloworld-sample)