Updated the adding languages documentation to reflect the changes for…

… multiple language servers

book/src/guides/adding_languages.md

@@ -16,14 +16,15 @@ injection-regex = "^mylang$"
 file-types = ["mylang", "myl"]
 comment-token = "#"
 indent = { tab-width = 2, unit = "  " }
-language-server = { command = "mylang-lsp", args = ["--stdio"] }
+language-servers = [ "mylang-lsp" ]
 ```
 
-These are the available keys and descriptions for the file.
+These are the available keys and descriptions for a language.
 
 | Key                   | Description                                                   |
 | ----                  | -----------                                                   |
 | `name`                | The name of the language                                      |
+| `language-id`         | The language-id for language servers, checkout the table at [TextDocumentItem](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocumentItem) for the right id |
 | `scope`               | A string like `source.js` that identifies the language. Currently, we strive to match the scope names used by popular TextMate grammars and by the Linguist library. Usually `source.<name>` or `text.<name>` in case of markup languages |
 | `injection-regex`     | regex pattern that will be tested against a language name in order to determine whether this language should be used for a potential [language injection][treesitter-language-injection] site. |
 | `file-types`          | The filetypes of the language, for example `["yml", "yaml"]`. Extensions and full file names are supported.  |
@@ -33,10 +34,76 @@ These are the available keys and descriptions for the file.
 | `diagnostic-severity` | Minimal severity of diagnostic for it to be displayed. (Allowed values: `Error`, `Warning`, `Info`, `Hint`) |
 | `comment-token`       | The token to use as a comment-token                           |
 | `indent`              | The indent to use. Has sub keys `tab-width` and `unit`        |
-| `language-server`     | The Language Server to run. Has sub keys `command` and `args` |
-| `config`              | Language Server configuration                                 |
+| `language-servers`    | The Language Servers used for this language. See below for more information   |
 | `grammar`             | The tree-sitter grammar to use (defaults to the value of `name`) |
 
+
+In case multiple language servers are specified, it's often useful to only enable certain language-server features for these language servers.
+For example `efm-lsp-prettier` (see in the next section for an example configuration for typescript) is used only with a formatting command `prettier`
+but everything else should be handled by the `typescript-language-server` (configured by default)
+The language configuration for typescript could look like this:
+
+```toml
+[[language]]
+name = "typescript"
+language-servers = [ { name = "efm-lsp-prettier", only-features = [ "format" ] }, "typescript-language-server" ]
+```
+
+or equivalent:
+
+```toml
+[[language]]
+name = "typescript"
+language-servers = [ { name = "typescript-language-server", except-features = [ "format" ] }, "efm-lsp-prettier" ]
+```
+
+Each requested LSP feature is priorized in the order of the `language-servers` array.
+
+The list of supported features are:
+
+- `format`
+- `goto-definition`
+- `goto-type-definition`
+- `goto-reference`
+- `goto-implementation`
+- `signature-help`
+- `hover`
+- `completion`
+- `code-action`
+- `document-symbols`
+- `workspace-symbols`
+- `diagnostics`
+- `rename-symbol`
+
+
+### Language server configuration
+
+Language servers are configured separately in the table `language-server` in the same file as the languages [`languages.toml`][languages.toml]
+
+
+```toml
+[langauge-server.mylang-lsp]
+command = "mylang-lsp"
+args = ["--stdio"]
+config = { provideFormatter = true }
+
+[language-server.efm-lsp-prettier]
+command = "efm-langserver"
+
+[language-server.efm-lsp-prettier.config]
+documentFormatting = true
+languages = { typescript = [ { formatCommand ="prettier --stdin-filepath ${INPUT}", formatStdin = true } ] }
+```
+
+These are the available keys and descriptions for a language server.
+
+| Key                   | Description                                                         |
+| ----                  | -----------                                                         |
+| `command`             | The command for the language server                                 |
+| `args`                | Arguments for the command                                           |
+| `config`              | Language Server configuration                                       |
+| `timeout`             | Timeout in seconds (default 20) for requests to the language server |
+
 When adding a new language or Language Server configuration for an existing
 language, run `cargo xtask docgen` to add the new configuration to the
 [Language Support][lang-support] docs before creating a pull request.