Merge pull request #295275 from mjbvz/dev/mjbvz/odd-gayal

Updating documentation for chatSessions proposal

src/vscode-dts/vscode.proposed.chatSessionsProvider.d.ts

@@ -35,6 +35,8 @@ declare module 'vscode' {
 		/**
 		 * Registers a new {@link ChatSessionItemProvider chat session item provider}.
 		 *
+		 * @deprecated Use {@linkcode createChatSessionItemController} instead.
+		 *
 		 * To use this, also make sure to also add `chatSessions` contribution in the `package.json`.
 		 *
 		 * @param chatSessionType The type of chat session the provider is for.
@@ -46,12 +48,21 @@ declare module 'vscode' {
 
 		/**
 		 * Creates a new {@link ChatSessionItemController chat session item controller} with the given unique identifier.
+		 *
+		 * To use this, also make sure to also add `chatSessions` contribution in the `package.json`.
+		 *
+		 * @param chatSessionType The type of chat session the provider is for.
+		 * @param refreshHandler The controller's {@link ChatSessionItemController.refreshHandler refresh handler}.
+		 *
+		 * @returns A new controller instance that can be used to manage chat session items for the given chat session type.
 		 */
-		export function createChatSessionItemController(id: string, refreshHandler: (token: CancellationToken) => Thenable<void>): ChatSessionItemController;
+		export function createChatSessionItemController(chatSessionType: string, refreshHandler: ChatSessionItemControllerRefreshHandler): ChatSessionItemController;
 	}
 
 	/**
 	 * Provides a list of information about chat sessions.
+	 *
+	 * @deprecated Use {@linkcode ChatSessionItemController} instead.
 	 */
 	export interface ChatSessionItemProvider {
 		/**
@@ -77,7 +88,12 @@ declare module 'vscode' {
 	}
 
 	/**
-	 * Provides a list of information about chat sessions.
+	 * Extension callback invoked to refresh the collection of chat session items for a {@linkcode ChatSessionItemController}.
+	 */
+	export type ChatSessionItemControllerRefreshHandler = (token: CancellationToken) => Thenable<void>;
+
+	/**
+	 * Manages chat sessions for a specific chat session type
 	 */
 	export interface ChatSessionItemController {
 		readonly id: string;
@@ -93,7 +109,7 @@ declare module 'vscode' {
 		readonly items: ChatSessionItemCollection;
 
 		/**
-		 * Creates a new managed chat session item that be added to the collection.
+		 * Creates a new managed chat session item that can be added to the collection.
 		 */
 		createChatSessionItem(resource: Uri, label: string): ChatSessionItem;
 
@@ -102,7 +118,7 @@ declare module 'vscode' {
 		 *
 		 * This is also called on first load to get the initial set of items.
 		 */
-		readonly refreshHandler: (token: CancellationToken) => Thenable<void>;
+		readonly refreshHandler: ChatSessionItemControllerRefreshHandler;
 
 		/**
 		 * Fired when an item's archived state changes.
@@ -121,7 +137,8 @@ declare module 'vscode' {
 
 		/**
 		 * Replaces the items stored by the collection.
-		 * @param items Items to store.
+		 *
+		 * @param items Items to store. If two items have the same resource URI, the last one will be used.
 		 */
 		replace(items: readonly ChatSessionItem[]): void;
 
@@ -136,31 +153,42 @@ declare module 'vscode' {
 		/**
 		 * Adds the chat session item to the collection. If an item with the same resource URI already
 		 * exists, it'll be replaced.
+		 *
 		 * @param item Item to add.
 		 */
 		add(item: ChatSessionItem): void;
 
 		/**
 		 * Removes a single chat session item from the collection.
+		 *
 		 * @param resource Item resource to delete.
 		 */
 		delete(resource: Uri): void;
 
 		/**
 		 * Efficiently gets a chat session item by resource, if it exists, in the collection.
+		 *
 		 * @param resource Item resource to get.
+		 *
 		 * @returns The found item or undefined if it does not exist.
 		 */
 		get(resource: Uri): ChatSessionItem | undefined;
 	}
 
+	/**
+	 * A chat session show in the UI.
+	 *
+	 * This should be created by calling a {@link ChatSessionItemController.createChatSessionItem createChatSessionItem}
+	 * method on the controller. The item can then be added to the controller's {@link ChatSessionItemController.items items collection}
+	 * to show it in the UI.
+	 */
 	export interface ChatSessionItem {
 		/**
 		 * The resource associated with the chat session.
 		 *
 		 * This is uniquely identifies the chat session and is used to open the chat session.
 		 */
-		resource: Uri;
+		readonly resource: Uri;
 
 		/**
 		 * Human readable name of the session shown in the UI