Conceptual overview missing

[phst]

The concepts "workspace" and "client" are fundamental for lsp-mode, but not well documented. There should be precise and exhaustive documentation about the fundamental abstractions that these types provide, their relationship with buffers and server processes, etc.

[phst]

I actually don't quite understand the difference between workspace and client myself. It seems there's one server process per workspace, and one client per buffer, but then there's more than one buffer per workspace, so that doesn't make much sense. How about merging the two structures into a single structure?

[alanz]

I am coming to the conclusion that they should be merged, as I think a workspace always has exactly one client.

[alanz]

Except I think we do need both.

The client is the template constructed by calling lsp-define-stdio-client (or lsp-define-tcp-client) and captures the specific features related to a given language server.

The workspace captures the specific instance of a running language server, started up by using the relevant client template.

So if you open up two different haskell projects (as determined by the get-root function of the client), then each will have its own workspace, but there is still only one haskell client. Or one way of constructing one, as created in the lsp-define-xxx-client macro.

[phst]

I am coming to the conclusion that they should be merged, as I think a workspace always has exactly one client.

That is what #289 would do.

The client is the template constructed by calling lsp-define-stdio-client (or lsp-define-tcp-client) and captures the specific features related to a given language server.
The workspace captures the specific instance of a running language server, started up by using the relevant client template.
So if you open up two different haskell projects (as determined by the get-root function of the client), then each will have its own workspace, but there is still only one haskell client. Or one way of constructing one, as created in the lsp-define-xxx-client macro.

This makes a lot of sense, but doesn't seem to match the code at all. It looks like right now we have one client per buffer (because ...-enable always creates a new client). The workspace then has a reference to a single arbitrary client and treats it as "the" client. So if we want to go that route, we need to change the code to actually match the concept:

• Have define-...-client create the client object.
• Move standard error buffer and last-id to the workspace.
• Figure out what to do with the :initialize keyword argument.

[alanz]

I am happy with either of those approaches.

[phst]

I think your suggestion is cleaner because it clearly separates the portions relating to a single server process from the "workspace factory" code. I'll send a PR.

[MaskRay]

One workspace can have multiple clients for different languages. See #335

The current usage of lsp--workspace-client should be generalized.

[yyoncho]

The documentation was extended in 7c55ba5 (e. g. https://github.com/emacs-lsp/lsp-mode/blob/master/lsp-mode.el#L610) please reopen if you think that it is not enough.