better doc for DebugConfigurationProvider.provideDebugAdapter

src/vs/vscode.proposed.d.ts

@@ -477,23 +477,38 @@ declare module 'vscode' {
 
 	export interface DebugConfigurationProvider {
 		/**
-		 * This optional method is called just before a debug adapter is started to determine its executable path and arguments.
-		 * Registering more than one debugAdapterExecutable for a type results in an error.
+		 * The optional method 'provideDebugAdapter' is called at the start of a debug session to provide details about the debug adapter to use.
+		 * These details must be returned as objects of type DebugAdapterDescriptor.
+		 * Currently two types of debug adapters are supported:
+		 * - a debug adapter executable specified as a command path and arguments (see DebugAdapterExecutable),
+		 * - a debug adapter server reachable via a communication port (see DebugAdapterServer).
+		 * If the method is not implemented the default behavior is this:
+		 *   provideDebugAdapter(session: DebugSession, folder: WorkspaceFolder | undefined, executable: DebugAdapterExecutable, config: DebugConfiguration, token?: CancellationToken) {
+		 *      if (typeof config.debugServer === 'number') {
+		 *         return new DebugAdapterServer(config.debugServer);
+		 *      }
+		 * 		return executable;
+		 *   }
+		 * Registering more than one provideDebugAdapter for a type results in an error.
+		 * @param session The [debug session](#DebugSession) for which the debug adapter will be used.
 		 * @param folder The workspace folder from which the configuration originates from or undefined for a folderless setup.
+		 * @param executable The debug adapter's executable information as specified in the package.json (or undefined if no such information exists).
+		 * @param config The resolved debug configuration.
 		 * @param token A cancellation token.
-		 * @return a [debug adapter's executable and optional arguments](#DebugAdapterExecutable) or undefined.
-		 * @deprecated Use DebugConfigurationProvider.provideDebugAdapter instead
+		 * @return a [debug adapter's descriptor](#DebugAdapterDescriptor) or undefined.
 		 */
-		debugAdapterExecutable?(folder: WorkspaceFolder | undefined, token?: CancellationToken): ProviderResult<DebugAdapterExecutable>;
+		provideDebugAdapter?(session: DebugSession, folder: WorkspaceFolder | undefined, executable: DebugAdapterExecutable | undefined, config: DebugConfiguration, token?: CancellationToken): ProviderResult<DebugAdapterDescriptor>;
 
 		/**
+		 * Deprecated, use DebugConfigurationProvider.provideDebugAdapter instead.
 		 * This optional method is called just before a debug adapter is started to determine its executable path and arguments.
-		 * Registering more than one provideDebugAdapter for a type results in an error.
+		 * Registering more than one debugAdapterExecutable for a type results in an error.
 		 * @param folder The workspace folder from which the configuration originates from or undefined for a folderless setup.
 		 * @param token A cancellation token.
-		 * @return a [debug adapter's descriptor](#DebugAdapterDescriptor) or undefined.
+		 * @return a [debug adapter's executable and optional arguments](#DebugAdapterExecutable) or undefined.
+		 * @deprecated Use DebugConfigurationProvider.provideDebugAdapter instead
 		 */
-		provideDebugAdapter?(session: DebugSession, folder: WorkspaceFolder | undefined, executable: DebugAdapterExecutable, config: DebugConfiguration, token?: CancellationToken): ProviderResult<DebugAdapterDescriptor>;
+		debugAdapterExecutable?(folder: WorkspaceFolder | undefined, token?: CancellationToken): ProviderResult<DebugAdapterExecutable>;
 	}
 
 	//#endregion