I'm working on better selecting an active parameter in the signature help for Python code. Python differs from many languages in that you can generally specify parameters in any order you'd like by naming them, or to have them be put into *args or **kwargs completely independently of their passed position. Because current signature help API (and thus its use in the LSP) only lets you specify one active parameter for the entire signature help response (versus one active parameter per signature), this is difficult to model.

VS Code and the LSP introduced a signature help context with retriggering, which can provide context about which signature the user has selected. However, a retrigger does not occur on a simple up/down navigation in the UI, so there is no way to use retriggers to fully allow a signature provider to change the active parameter to match the active signature. In microsoft/vscode-languageserver-node#608, I suggested having VS Code retrigger on this type of navigation as it does for left/right cursor movements, but this presumably may be too much of a behavior change (though I don't personally think it's any more expensive than when the cursor is moved left/right).

What I am really looking for is a way to be able to specify per-signature which parameter is the active one. This means that during navigation the UI would not need to do any extra requests to know which parameter to show as active when an alternate signature is selected; the signature already contains this info.

There are two ways I can see this being done. Either add activeParameter?: number to the SignatureInformation class, like:

class SignatureInformation {
	label: string;
	documentation?: string | MarkdownString;
	parameters: ParameterInformation[];
	activeParameter?: number; // NEW: an index into the above parameters array
}

Or to add a property to ParameterInformation:

class ParameterInformation {
	label: string | [number, number];
	documentation?: string | MarkdownString;
	active?: boolean; // NEW: true if the UI should highlight this as active
}

I am unsure which is more natural, but my assumption is the former given it's close to the current implementation indexes, and how it disallows multiple parameters from being active at once.

I find this to be a clearer API than having a single active parameter for the entire signature help. To maintain backwards compatibility, if the new activeParameter property is set on a signature, then it could take precedence over the old top-level value (which I believe is stuck as a non-optional number and cannot be omitted).

To support this, here is an example usecase.

Take the following Python code, which uses typing annotations to hint the user on valid signatures (and for potential type checking in addition to a better editor experience):

from typing import Any, Optional, overload

@overload
def func(a: int) -> int: ...

@overload
def func(a: int, b: int, c: int = 1234, d: Optional[str] = None, **kwargs: Any) -> str: ...

def func(*args, **kwargs):
    # Real implementation here.
    # This might be in a .py file while the above is in a stub distributed separately.

Assume the user is typing out a call, like:

func(1234|)

Where | is the cursor. For this, any of the three known signatures are reasonable candidates. I will highlight each signature below with their intended active parameter with <>:

(<a: int>) -> int
(<a: int>, b: int, c: int = 1234, d: Optional[str] = None, **kwargs: Any) -> str
(<*args>, **kwargs)

There's no problem yet; they all have the same active parameter index, 0. Navigation will appear to work; the first parameter is selected in all cases.

Now, change the user's code to:

func(1234, d=|)

The signatures should look like this:

(a: int) -> int
(a: int, b: int, c: int = 1234, <d: Optional[str] = None>, **kwargs: Any) -> str
(*args, <**kwargs>)

The active parameter indexes are different. d will go to the d=... of the second signature, but the **kwargs of the third. The first has no active parameter, as the call no longer fits.

Currently, we can only indicate a single active signature (index 1) and its active parameter (index 3). But if the user navigates down to the next signature, there's nothing we can do to change the parameter index and say the UI should be highlighting **kwargs instead. With the new API, each signature would state which parameter is the one that'd be active, and things work.

This is not a problem in a language like TypeScript, where optional parameters are just syntactic sugar and you must provide them in order left to right. In that case, the index always works for every signature; signatures where the index goes out of range simply don't have their parameter highlighted and it all works out implicitly.

This was split off of microsoft/vscode-languageserver-node#608. cc @mjbvz, @jrieken, @dbaeumer