As far as I know, the LSP specification only accepts PRs once there is a reference implementation. So you can literally just run VS Code with verbose logging turned on for the reference language server and inspect the communications.
I did my learning by literally following the VS Code guide (the reference implementation) https://code.visualstudio.com/api/language-extensions/progra... and implementing each feature one by one.
You simply return an object following the interface and features magically work. It's wonderful. I added the "Outline" feature in VS Code, and the similar feature to show all symbols in a file in vim in about 2 hours.
> And many of the concepts, like what a 'code lens' is, what properties it has, and how it would appear in an editor are never explained=
Well, no, because they're not specified. How vim displays a code lens might be very different to how VS code does.
“You have to run VSCode to reach a working understanding” seems like a pretty far cry from the stated goal of the project of decoupling the language features from the code editor to me
Well that and use utf-8 string indexing (which is easier for every other language than javascript): https://github.com/microsoft/language-server-protocol/issues...
I've been working on an LSP implementation lately, and I have to say so far the reality falls short of the promise. I feel like what LSP should be is a clear, simple interface for implementing IDE-like features for any language, but my experience is that it is incredibly arcane and difficult to use.
The main issue is the documentation. It has a high-level intro about what LSP is, which is basically marketing, and then it has some sort-of details about (maybe) all the interfaces supported by LSP. But I was sorely lacking that "middle" documentation about how to practically get set up and do things. I had to piece a lot of things together through blog posts, and reverse engineering mature LSP implementations like rust-analyzer. And the documentation you do have of the individual interfaces is kind of weird. Like LSP is a JSON-RPC protocol, but documentation of the objects involved is all C# code, which is never really explained. And many of the concepts, like what a 'code lens' is, what properties it has, and how it would appear in an editor are never explained, so you just have to look up VSCode documentation to figure out what any of this means.
I feel like LSP is sold as a general framework for IDE-independence, but working with it feels a lot more like you've just given access to some of the internal API's in VSCode via JSON-RPC, and other editors have just adapted to this.
LSP is a great concept, but I can imagine if you really approached this problem from scratch, you could probably reach a much better, more sensible result.