From e7a17105bdea3054c96d4f7363249c8686ae0951 Mon Sep 17 00:00:00 2001
From: Joyce Er <joyce.er@microsoft.com>
Date: Fri, 26 May 2023 11:53:55 -0700
Subject: [PATCH] Document `ShareProvider` API proposal (#183568)

* Document `ShareProvider` API proposal

* Remove mention of VS Code from JSDoc
---
 .../vscode.proposed.shareProvider.d.ts        | 52 +++++++++++++++++--
 1 file changed, 48 insertions(+), 4 deletions(-)

diff --git a/src/vscode-dts/vscode.proposed.shareProvider.d.ts b/src/vscode-dts/vscode.proposed.shareProvider.d.ts
index 6470557cac1..49b36c009e8 100644
--- a/src/vscode-dts/vscode.proposed.shareProvider.d.ts
+++ b/src/vscode-dts/vscode.proposed.shareProvider.d.ts
@@ -3,27 +3,71 @@
  *  Licensed under the MIT License. See License.txt in the project root for license information.
  *--------------------------------------------------------------------------------------------*/
 
-// https://github.com/microsoft/vscode/issues/176316
+// https://github.com/microsoft/vscode/issues/176316 @joyceerhl
 
 declare module 'vscode' {
-	export interface TreeItem {
-		shareableItem?: ShareableItem;
-	}
 
+	/**
+	 * Data about an item which can be shared.
+	 */
 	export interface ShareableItem {
+		/**
+		 * A resource in the editor that can be shared.
+		 */
 		resourceUri: Uri;
+
+		/**
+		 * If present, a selection within the `resourceUri`.
+		 */
 		selection?: Range;
 	}
 
+	/**
+	 * A provider which generates share links for resources in the editor.
+	 */
 	export interface ShareProvider {
+
+		/**
+		 * A unique ID for the provider.
+		 * This will be used to activate specific extensions contributing share providers if necessary.
+		 */
 		readonly id: string;
+
+		/**
+		 * A label which will be used to present this provider's options in the UI.
+		 */
 		readonly label: string;
+
+		/**
+		 * The order in which the provider should be listed in the UI when there are multiple providers.
+		 */
 		readonly priority: number;
 
+		/**
+		 *
+		 * @param item Data about an item which can be shared.
+		 * @param token A cancellation token.
+		 * @returns An {@link Uri} which will be copied to the user's clipboard and presented in a confirmation dialog.
+		 */
 		provideShare(item: ShareableItem, token: CancellationToken): ProviderResult<Uri>;
 	}
 
 	export namespace window {
+
+		/**
+		 * Register a share provider. An extension may register multiple share providers.
+		 * There may be multiple share providers for the same {@link ShareableItem}.
+		 * @param selector A document selector to filter whether the provider should be shown for a {@link ShareableItem}.
+		 * @param provider A share provider.
+		 */
 		export function registerShareProvider(selector: DocumentSelector, provider: ShareProvider): Disposable;
 	}
+
+	export interface TreeItem {
+
+		/**
+		 * An optional property which, when set, inlines a `Share` option in the context menu for this tree item.
+		 */
+		shareableItem?: ShareableItem;
+	}
 }