Update port attributes API (#182761)

Add doc updates and make selector a type.
Part of #115616

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

@@ -8,11 +8,29 @@ declare module 'vscode' {
 	// https://github.com/microsoft/vscode/issues/115616 @alexr00
 
 	export enum PortAutoForwardAction {
+		/**
+		 * Notify the user that the port is being forwarded. This is the default action.
+		 */
 		Notify = 1,
+		/**
+		 * Once the port is forwarded, open the browser to the forwarded port.
+		 */
 		OpenBrowser = 2,
+		/**
+		 * Once the port is forwarded, open the preview browser to the forwarded port.
+		 */
 		OpenPreview = 3,
+		/**
+		 * Forward the port silently.
+		 */
 		Silent = 4,
+		/**
+		 * Do not forward the port.
+		 */
 		Ignore = 5,
+		/**
+		 * Once the port is forwarded, open the browser to the forwarded port. Only open the browser the first time the port is forwarded in a session.
+		 */
 		OpenBrowserOnce = 6
 	}
 
@@ -49,6 +67,26 @@ declare module 'vscode' {
 		providePortAttributes(port: number, pid: number | undefined, commandLine: string | undefined, token: CancellationToken): ProviderResult<PortAttributes>;
 	}
 
+	export interface PortAttributesProviderSelector {
+		/**
+		 * TODO:  @alexr00 no one is currently using this. Should we delete it?
+		 * If your {@link PortAttributesProvider PortAttributesProvider} is registered after your process has started then already know the process id of port you are listening on.
+		 * Specifying a pid will cause your provider to only be called for ports that match the pid.
+		 */
+		pid?: number;
+
+		/**
+		 * Specifying a port range will cause your provider to only be called for ports within the range.
+		 */
+		portRange?: [number, number];
+
+		/**
+		 * TODO: @alexr00 no one is currently using this. Should we delete it?
+		 * Specifying a command pattern will cause your provider to only be called for processes whose command line matches the pattern.
+		 */
+		commandPattern?: RegExp;
+	}
+
 	export namespace workspace {
 		/**
 		 * If your extension listens on ports, consider registering a PortAttributesProvider to provide information
@@ -56,13 +94,12 @@ declare module 'vscode' {
 		 * this information with a PortAttributesProvider the extension can tell the editor that these ports should be
 		 * ignored, since they don't need to be user facing.
 		 *
-		 * @param portSelector If registerPortAttributesProvider is called after you start your process then you may already
-		 * know the range of ports or the pid of your process. All properties of a the portSelector must be true for your
-		 * provider to get called.
-		 * The `portRange` is start inclusive and end exclusive.
-		 * The `commandPattern` is a regular expression that will be matched against the command line of the process.
-		 * @param provider The PortAttributesProvider
+		 * The results of the PortAttributesProvider are merged with the user setting `remote.portsAttributes`. If the values conflict, the user setting takes precedence.
+		 *
+		 * @param portSelector It is best practice to specify a port selector to avoid unnecessary calls to your provider.
+		 * If you don't specify a port selector your provider will be called for every port, which will result in slower port forwarding for the user.
+		 * @param provider The {@link PortAttributesProvider PortAttributesProvider}.
 		 */
-		export function registerPortAttributesProvider(portSelector: { pid?: number; portRange?: [number, number]; commandPattern?: RegExp }, provider: PortAttributesProvider): Disposable;
+		export function registerPortAttributesProvider(portSelector: PortAttributesProviderSelector, provider: PortAttributesProvider): Disposable;
 	}
 }