Add context information to SignatureHelpProvider

[mjbvz]

Problem
Signature help providers sometimes need more information to determine which signature to return. microsoft/TypeScript#1150 for example discusses how typing a comma inside of a string could mistakenly triggering TypeScript signature help. Using the current VS Code api, a signature help provider cannot easily distinguish the cases:

• User just typed a comma in a string, triggering signature help.
• Cursor is after a comma in a string and the user manually requested signature help.

Proposal
Add a context when requesting signature help. This context should supply at least the following:

• The character that triggered signature help (optional)
• Why signature help was triggered (manual, typing, retrigger, ...)

This proposal is based on what typescript has implemented which in turn is based on rosyln

retriggger presents one additional complication. This is needed for nested function calls and would be invoked when you type a closing brace with signature help already showing, such as:

console.log(1, Math.max(1, 2)|   )

when the user has just typed ). See Daniel's comment for more context: microsoft/TypeScript#1150 (comment)

[Gama11]

Same as #34737 / maybe one should be closed?

[mjbvz]

Prototype PR up at #58135

I'd like feedback on the proposed api from a few other language authors to make sure we design an api that will work well for a variety of languages. /cc @DonJayamanne @DustinCampbell @DanTup @ramya-rao-a @aeschli @fbricon @DanielRosenwasser

Some starting questions:

• Does your extension / language server have a need for this extra context when computing signature help?
• Are there other pieces of context beyond what is currently proposed that would be helpful?
• Any concerns about the trigger reasons?

Also @dbaeumer heads-up for language server protocol

[DanTup]

Whoops - I hadn't noticed this was missing (and require it to implement automatic triggering in a way that doesn't annoy users).

The proposal looks good for me, though we'd planned on not requiring the specific character in the API to the server but rather just whether it was automatically triggered (and if not, only return data of the offset is in a position that is the start of an argument).

[mjbvz]

Reopening :)

API is still in-design but I've merged in the current proposal so that we can get some real world testing of how the current design works for javascript and typescript. Please continue to share feedback here

[KamasamaK]

Are there other pieces of context beyond what is currently proposed that would be helpful?

Yes, the client value of activeSignature. See #33413

[mjbvz]

#33413 will likely not be in first edition of this api but we've designed the api so that this data could be introduced easily in the future.

Current proposal is:

/**
 * How a [Signature provider](#SignatureHelpProvider) was triggered
 */
export enum SignatureHelpTriggerReason {
	/**
	 * Signature help was invoked manually by the user or by a command.
	 */
	Invoke = 1,

	/**
	 * Signature help was triggered by a trigger character.
	 */
	TriggerCharacter = 2,

	/**
	 * Signature help was triggered by the cursor moving or by the document content changing.
	 */
	ContentChange = 3,
}

/**
 * Contains additional information about the context in which a
 * [signature help provider](#SignatureHelpProvider.provideSignatureHelp) is triggered.
 */
export interface SignatureHelpContext {
	/**
	 * Action that caused signature help to be requested.
	 */
	readonly triggerReason: SignatureHelpTriggerReason;

	/**
	 * Character that caused signature help to be requested.
	 *
	 * This is `undefined` when signature help is not triggered by typing, such as when invoking signature help
	 * or when moving the cursor.
	 */
	readonly triggerCharacter?: string;

	/**
	 * Whether or not signature help was previously showing when triggered.
	 *
	 * Retriggers occur when the signature help is already active and can be caused by typing a trigger character
	 * or by a cursor move.
	 */
	readonly isRetrigger: boolean;
}

export interface SignatureHelpProvider {
	provideSignatureHelp(document: TextDocument, position: Position, token: CancellationToken, context: SignatureHelpContext): ProviderResult<SignatureHelp>;
}

export interface SignatureHelpProviderMetadata {
	readonly triggerCharacters: ReadonlyArray<string>;
	readonly retriggerCharacters: ReadonlyArray<string>;
}

namespace languages {
	export function registerSignatureHelpProvider(
		selector: DocumentSelector,
		provider: SignatureHelpProvider,
		metadata: SignatureHelpProviderMetadata
	): Disposable;
}

Will try finalizing next iteration. Possible changes at the moment:

• Rename ContentChange or split it up to make it more clear what this tracks

• Make isRetrigger only be true if the signature help widget was showing. Currently it is also true if the signature help will show at some point in the future. This is the root cause of Signature help inappropriately fired in totally unrealistic scenario #58492

  An alternative design would be to change isRetrigger to state or something similar that can be Inactive, Pending, or Showing.

[DanTup]

Is this being considered for LSP too? It's likely I'll get around to implementing it in an LSP server before the extension directly (since our existing server protocol doesn't support it, but for LSP I'm implementing it server-side).

[dbaeumer]

Yes, this will very likely make its way into LSP as well.