Clarify docs on CompletionList.isIncomplete to make it very clear the behaviour when using backspace

[DanTup]

I've raised a request for the LSP spec to be explicit about this behaviour, but since it's possible to use the VS Code APIs without LSP I believe it should be concrete here too.

There is a flag on CompletionList called isIncomplete which informs VS Code that it needs to re-query the server as the user continues to type when the suggestion list is visible (rather than just filtering client-side).

What is not clear from the spec, is the behaviour of when isIncomplete=false in the case where the user presses <backspace>.

For example, let's say my completion list simple has:

• one
• two
• three

If the user invokes completion where ^ is here:

print(on^

If the server is using IsIncomplete=false (eg. it's providing the "full list"), should it include two and three here, on the assumption that the client will not call the server again even if the user hits backspace, or should it assume that the client-side filtering is only for typing forwards?

I did some testing of this and found:

• If you type a single character to trigger completion, then hit backspace, the completion widget closes
• If you type several characters to trigger completion, then backspace - the completion widget does not go back to the server if the original completion request was made before you'd typed the character you deleted (eg. it can be assumed the server had already included all relevant completions)
• If you invoke backspace with an existing prefix and then backspace (such that you now have a shorter prefix than was sent to the server), then it does re-call the server

Therefore, I've concluded that it's always safe for the server to filter based on the current prefix, and can assume if the user backspaces back past the prefix that existed when the server was called, VS Code will re-request the items. However, the spec is not at all detailed on this - it simply says:

• This list is not complete. Further typing should result in recomputing this list.

If this assumption can be clarified/guaranteed, then we can probably significantly improve the performance of completion in many situations (for example when using LiveShare, the whole list ends up being sent over the web, and we could drop around 25/26ths of the data if we could filter on the initial character that triggered completion).

[DanTup]

@jrieken @dbaeumer this is simply a request to clarify something that's not clear in the docs - does this really need votes? This isn't relevant to end users but it's important to ensure extensions don't make assumptions that might break in the future.

[dbaeumer]

@jrieken: I remember that we once discussed this and that the outcome was that backspace should always trigger a new request if it moves the cursor before the last trigger point. Is this still correct?