Better document

[Jack-Works]

It's hard to guess what an ability does, the specification is vague. I hope there is a screen recording/diff image (before-after) or something for each ability else to make it easier to understand.

Here are some questions I've met.

To provide type-aware code highlights, which one should I implement? Document Highlight or Document Color? No, it's Semantic Tokens.

What's the benefit of implementing Document Highlights? It looks like my editor (VSCode) already provides highlight when I selecting a text. The answer is (afaik), we can do scope analysis.

import { a } from 'mod'
function f(a) {
    a // highlights "a" in line 2 but not line 1 or line 5
}
a // highlights "a" in line 1 but not line 2 or line 3

Should I implement Document Link? What's the typical use case of it? What's the difference between Goto Definition?

What does Selection Range do? Is it related to the editor's "expand selection range" functionality?

What's the difference between Inline Value and Inlay Hint?

What is Monikers? Should I implement it? What can it do?

What's the difference between Signature Help and Hover?

I have experience with HTML and JSX so I know what Linked Editing Range can do. This can be unclear for other implementors that if they should implement this.

[dbaeumer]

Some of these features are documents here: https://code.visualstudio.com/api/language-extensions/programmatic-language-features

Instead of adding something to the specification itself I think the overall VS Code documentation would benefit from something like this as well.

[davidhalter]

I have been in the same position at times. Personally it would have helped me a lot if the features you linked would be linked in the specification with a ("implemented in VSCode like ...").

Some of the LSP only become understandable if you have actually seen what VSCode does.

[mfussenegger]

Instead of adding something to the specification itself I think the overall VS Code documentation would benefit from something like this as well.

I think this risks making server implementations even more vscode specific - given that there's already a tendency towards vscode overfit I think it would be benificial to have some examples of how a feature might be used in the specification. Ideally also showcasing how other editors may use something in a different way if applicable.

[michaelpj]

The LSP spec makes the (IMO brilliant) choice of focussing on presentation, but that does mean that it's really really important to know what the presentation actually is (e.g. here's one of my questions about this).

The reality is that VSCode is the reference implementation for the presentation side, so we can use that, but it is IMO morally part of the spec, and so I do think it would be very helpful to include that information in the spec.