Add more notes to selectChatModels (microsoft#213867)

Author: roblourens

src/vscode-dts/vscode.d.ts

@@ -19042,7 +19042,7 @@ declare module 'vscode' {
 		readonly id: string;
 
 		/**
-		 * A well-know identifier of the vendor of the language model, a sample is `copilot`, but
+		 * A well-known identifier of the vendor of the language model. An example is `copilot`, but
 		 * values are defined by extensions contributing chat models and need to be looked up with them.
 		 */
 		readonly vendor: string;
@@ -19195,12 +19195,11 @@ declare module 'vscode' {
 		export const onDidChangeChatModels: Event<void>;
 
 		/**
-		 * Select chat models by a {@link LanguageModelChatSelector selector}. This can yield in multiple or no chat models and
+		 * Select chat models by a {@link LanguageModelChatSelector selector}. This can yield multiple or no chat models and
 		 * extensions must handle these cases, esp. when no chat model exists, gracefully.
 		 *
 		 * ```ts
-		 *
-		 * const models = await vscode.lm.selectChatModels({family: 'gpt-3.5-turbo'})!;
+		 * const models = await vscode.lm.selectChatModels({ family: 'gpt-3.5-turbo' });
 		 * if (models.length > 0) {
 		 * 	const [first] = models;
 		 * 	const response = await first.sendRequest(...)
@@ -19210,7 +19209,11 @@ declare module 'vscode' {
 		 * }
 		 * ```
 		 *
-		 * *Note* that extensions can hold-on to the results returned by this function and use them later. However, when the
+		 * A selector can be written to broadly match all models of a given vendor or family, or it can narrowly select one model by ID.
+		 * Keep in mind that the available set of models will change over time, but also that prompts may perform differently in
+		 * different models.
+		 *
+		 * *Note* that extensions can hold on to the results returned by this function and use them later. However, when the
 		 * {@link onDidChangeChatModels}-event is fired the list of chat models might have changed and extensions should re-query.
 		 *
 		 * @param selector A chat model selector. When omitted all chat models are returned.