Expose a stopDebugging API to extensions

[connor4312]

We have vscode.debug.startDebugging to start a debug sessions, which is quite useful.

I wanted to write some tests for teardown behavior of js-debug, and when trying to do so I ran into the problem that there's no equivalent stopDebugging API. I could manually send some "terminate" request, but this doesn't cover the full scenario as effectively.

I'd like to propose the addition of a simple new API:

export function stopDebugging(session: DebugSession): Promise<void>

cc @weinand

[weinand]

IMO there are two APIs possible:

A new terminate method on the DebugSession:

	export interface DebugSession {

		/**
		 * Terminates the session.
		 */
		terminate(): Thenable<void>;
	}

This approach is similar to TaskExecution.terminate() and the name "terminate" matches the already existing onDidTerminateDebugSession
.

Or a new function vscode.debug.stopDebugging:

	export namespace debug {

		/**
		 * Stop the given debug session or if no session is given stop all sessions.
		 */
		export function stopDebugging(session?: DebugSession): Thenable<void>;
	}

stopDebugging matches startDebugging and the optional session matches our internal semantics of IDebugService.stopSession.

@connor4312 @isidorn opinions?

[connor4312]

This approach is similar to TaskExecution.terminate() and the name "terminate" matches the already existing onDidTerminateDebugSession

One point of confusion here is that "stop debugging" for attach configurations will send disconnect rather than terminate. We could alternately rename it something like stop().

Personally I like the symmetry between vscode.debug.startDebugging and stopDebugging. But I don't feel strongly.

[weinand]

I've released both variants of the API to proposed.

@connor4312 I agree that "terminate" does not convey the semantics in a good way. And I like the symmetry between startDebugging and stopDebugging too.

So I will push vscode.debug.stopDebugging through the API process...

[weinand]

Proposal:

Similar to the already existing vscode.debug.startDebugging we introduce a new function vscode.debug.stopDebugging:

	export namespace debug {

		/**
		 * Stop the given debug session or if no session is given stop all sessions.
		 */
		export function stopDebugging(session?: DebugSession): Thenable<void>;
	}

stopDebugging matches startDebugging and the optional session matches our internal semantics of IDebugService.stopSession.

[isidorn]

The proposal makes sense to me. Making it symetric to startDebugging feels like the way to go for me.

[weinand]

Testing of the proposed API will be done in July, finalization will take place in August.

[weinand]

After incorporating the feedback from the test pass the final proposed API has become this:

		/**
		 * Stop the given debug session or stop all debug sessions if session is omitted.
		 * @param session The [debug session](#DebugSession) to stop; if omitted all sessions are stopped.
		 */
		export function stopDebugging(session?: DebugSession): Thenable<void>;