docs: unverbose, mention "settings" param

Problem: - The docs are verbose. - The "settings" param is not really clarified anywhere. Solution: - Mention the "settings" param in the README. - Tighten up the wording. - Remove the "Use a loop to conveniently call 'setup'..." advice in the docs. It confuses users and doesn't really save much code. - Start to reduce the scope of nvim-lspconfig. - For example, it is redundant for it to document general LSP things. Thus, the help section *lspconfig-lsp* was removed. closes neovim#1951
Creativty · Jun 13, 2022 · 4f94bf5 · 4f94bf5
1 parent 86f9c29
commit 4f94bf5
Show file tree

Hide file tree

Showing 8 changed files with 114 additions and 166 deletions.
diff --git a/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md
@@ -3,9 +3,3 @@ name: Pull Request
 about: Submit a pull request
 title: ''
 ---
-
-<!--
-If you want to make changes to the README.md, do so in scripts/README_template.md.
-The CONFIG.md is auto-generated with all the options from the various LSP configuration;
-do not edit it manually
--->
diff --git a/CONFIG.md b/CONFIG.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -125,7 +125,7 @@ PRs are checked with [luacheck](https://github.com/mpeterv/luacheck), [StyLua](h
 
 ## Generating docs
 
-Github Actions automatically generates `server_configurations.md`. Only modify `scripts/README_template.md` or the `docs` table in the server config (the lua file). Do not modify `server_configurations.md` directly.
+Github Actions automatically generates `server_configurations.md`. Only modify `scripts/README_template.md` or the `docs` table in the server config Lua file. Do not modify `server_configurations.md` directly.
 
 To preview the generated `server_configurations.md` locally, run `scripts/docgen.lua` from
 `nvim` (from the project root):

diff --git a/LICENSE.md b/LICENSE.md
@@ -1,8 +1,8 @@
 Copyright Neovim contributors. All rights reserved.
 
-nvim-lsp is licensed under the terms of the Apache 2.0 license.
+nvim-lspconfig is licensed under the terms of the Apache 2.0 license.
 
-nvim-lsp's license follows:
+nvim-lspconfig's license follows:
 
 ====
                                  Apache License

diff --git a/README.md b/README.md
@@ -10,47 +10,40 @@ See also `:help lspconfig`.
 
 ## Install
 
-* Requires [Neovim v0.6.1](https://github.com/neovim/neovim/releases/tag/v0.6.1) or [Nightly](https://github.com/neovim/neovim/releases/tag/nightly). Update Neovim and 'lspconfig' before reporting an issue.
-
-* Install 'lspconfig' like any other Vim plugin, e.g. with [packer.nvim](https://github.com/wbthomason/packer.nvim):
-
-    ```lua
-    local use = require('packer').use
-    require('packer').startup(function()
-      use 'wbthomason/packer.nvim' -- Package manager
-      use 'neovim/nvim-lspconfig' -- Collection of configurations for the built-in LSP client
-    end)
-    ```
+* Requires [Neovim 0.7](https://github.com/neovim/neovim/releases/tag/v0.6.1) or [Nightly](https://github.com/neovim/neovim/releases/tag/nightly). Update Nvim and nvim-lspconfig before reporting an issue.
+* Install nvim-lspconfig like any other Vim plugin, e.g. with [packer.nvim](https://github.com/wbthomason/packer.nvim):
+  ```lua
+  local use = require('packer').use
+  require('packer').startup(function()
+    use 'wbthomason/packer.nvim' -- Package manager
+    use 'neovim/nvim-lspconfig' -- Configurations for Nvim LSP
+  end)
+  ```
 
 ## Quickstart
 
 1. Install a language server, e.g. [pyright](doc/server_configurations.md#pyright)
-
-    ```bash
-    npm i -g pyright
-    ```
-
+   ```bash
+   npm i -g pyright
+   ```
 2. Add the language server setup to your init.lua.
-
-    ```lua
-    require'lspconfig'.pyright.setup{}
-    ```
-
-3. Launch neovim, the language server will now be attached and providing diagnostics (see `:LspInfo`)
-
-    ```
-    nvim main.py
-    ```
-
-4. See [Keybindings and completion](#Keybindings-and-completion) for mapping useful functions and enabling omnifunc completion
-
-For a full list of servers, see [server_configurations.md](doc/server_configurations.md) or `:help lspconfig-server-configurations`. This document contains installation instructions and additional, optional, customization suggestions for each language server. For some servers that are not on your system path (e.g., `jdtls`, `elixirls`), you will be required to manually add `cmd` as an entry in the table passed to `setup`. Most language servers can be installed in less than a minute.
+   ```lua
+   require'lspconfig'.pyright.setup{}
+   ```
+3. Launch Nvim, the language server will attach and provide diagnostics.
+   ```
+   nvim main.py
+   ```
+4. Run `:LspInfo` to see the status or to troubleshoot.
+5. See [Keybindings and completion](#Keybindings-and-completion) to setup common mappings and omnifunc completion.
+
+See [server_configurations.md](doc/server_configurations.md) (`:help lspconfig-all` from Nvim) for the full list of configs, including installation instructions and additional, optional, customization suggestions for each language server. For servers that are not on your system path (e.g., `jdtls`, `elixirls`), you must manually add `cmd` to the `setup` parameter. Most language servers can be installed in less than a minute.
 
 ## Suggested configuration
 
-'lspconfig' does not map keybindings or enable completion by default. The following example configuration provides suggested keymaps for the most commonly used language server functions, and manually triggered completion with omnifunc (\<c-x\>\<c-o\>).
+nvim-lspconfig does not set keybindings or enable completion by default. The following example configuration provides suggested keymaps for the most commonly used language server functions, and manually triggered completion with omnifunc (\<c-x\>\<c-o\>).
 
-Note: **you must pass the defined `on_attach` as an argument to every `setup {}` call** and **the keybindings in `on_attach` only take effect on buffers with an active language server**. 
+Note: you must pass the defined `on_attach` as an argument to **every `setup {}` call** and the keybindings in `on_attach` **only take effect on buffers with an active language server**. 
 
 ```lua
 -- Mappings.
@@ -87,36 +80,40 @@ local on_attach = function(client, bufnr)
   vim.keymap.set('n', '<space>f', vim.lsp.buf.formatting, bufopts)
 end
 
--- Use a loop to conveniently call 'setup' on multiple servers and
--- map buffer local keybindings when the language server attaches
-local servers = { 'pyright', 'rust_analyzer', 'tsserver' }
-for _, lsp in pairs(servers) do
-  require('lspconfig')[lsp].setup {
+local lsp_flags = {
+  -- This is the default in Nvim 0.7+
+  debounce_text_changes = 150,
+}
+require('lspconfig')['pyright'].setup{
+    on_attach = on_attach,
+    flags = lsp_flags,
+}
+require('lspconfig')['tsserver'].setup{
+    on_attach = on_attach,
+    flags = lsp_flags,
+}
+require('lspconfig')['rust_analyzer'].setup{
     on_attach = on_attach,
-    flags = {
-      -- This will be the default in neovim 0.7+
-      debounce_text_changes = 150,
+    flags = lsp_flags,
+    -- Server-specific settings...
+    settings = {
+      ["rust-analyzer"] = {}
     }
-  }
-end
+}
 ```
 
-Manual, triggered completion is provided by neovim's built-in omnifunc. For **auto**completion, a general purpose [autocompletion plugin](https://github.com/neovim/nvim-lspconfig/wiki/Autocompletion) is required. 
+Manual, triggered completion is provided by Nvim's builtin omnifunc. For *auto*completion, a general purpose [autocompletion plugin](https://github.com/neovim/nvim-lspconfig/wiki/Autocompletion) is required. 
 
-## Debugging
+## Troubleshooting
 
-If you have an issue with 'lspconfig', the first step is to reproduce with a [minimal configuration](https://github.com/neovim/nvim-lspconfig/blob/master/test/minimal_init.lua).
+If you have an issue, the first step is to reproduce with a [minimal configuration](https://github.com/neovim/nvim-lspconfig/blob/master/test/minimal_init.lua).
 
 The most common reasons a language server does not start or attach are:
 
-1. The language server is not installed. 'lspconfig' does not install language servers for you. You should be able to run the `cmd` defined in each server's lua module from the command line and see that the language server starts. If the `cmd` is an executable name instead of an absolute path to the executable, ensure it is on your path.
-
+1. The language server is not installed. nvim-lspconfig does not install language servers for you. You should be able to run the `cmd` defined in each server's Lua module from the command line and see that the language server starts. If the `cmd` is an executable name instead of an absolute path to the executable, ensure it is on your path.
 2. Missing filetype plugins. Certain languages are not detecting by vim/neovim because they have not yet been added to the filetype detection system. Ensure `:set ft?` shows the filetype and not an empty value.
-
 3. Not triggering root detection. **Some** language servers will only start if it is opened in a directory, or child directory, containing a file which signals the *root* of the project. Most of the time, this is a `.git` folder, but each server defines the root config in the lua file. See [server_configurations.md](doc/server_configurations.md) or the source for the list of root directories.
-
 4. You must pass `on_attach` and `capabilities` for **each** `setup {}` if you want these to take effect. 
-
 5. **Do not call `setup {}` twice for the same server**. The second call to `setup {}` will overwrite the first.
 
 Before reporting a bug, check your logs and the output of `:LspInfo`. Add the following to your init.vim to enable logging:
@@ -132,19 +129,16 @@ Attempt to run the language server, and open the log with:
 ```
 Most of the time, the reason for failure is present in the logs.
 
-## Built-in commands
+## Commands
 
 * `:LspInfo` shows the status of active and configured language servers.
-
-The following support tab-completion for all arguments:
-
 * `:LspStart <config_name>` Start the requested server name. Will only successfully start if the command detects a root directory matching the current config. Pass `autostart = false` to your `.setup{}` call for a language server if you would like to launch clients solely with this command. Defaults to all servers matching current buffer filetype.
 * `:LspStop <client_id>` Defaults to stopping all buffer clients.
 * `:LspRestart <client_id>` Defaults to restarting all buffer clients.
 
-## The wiki
+## Wiki
 
-Please see the [wiki](https://github.com/neovim/nvim-lspconfig/wiki) for additional topics, including:
+See the [wiki](https://github.com/neovim/nvim-lspconfig/wiki) for additional topics, including:
 
 * [Automatic server installation](https://github.com/neovim/nvim-lspconfig/wiki/Installing-language-servers#automatically)
 * [Snippets support](https://github.com/neovim/nvim-lspconfig/wiki/Snippets)
@@ -154,16 +148,11 @@ Please see the [wiki](https://github.com/neovim/nvim-lspconfig/wiki) for additio
 ## Contributions
 
 If you are missing a language server on the list in [server_configurations.md](doc/server_configurations.md), contributing
-a new configuration for it would be appreciated. You can follow these steps:
+a new configuration for it helps others, especially if the server requires special setup. Follow these steps:
 
 1. Read [CONTRIBUTING.md](CONTRIBUTING.md).
-
 2. Create a new file at `lua/lspconfig/server_configurations/SERVER_NAME.lua`.
-
     - Copy an [existing config](https://github.com/neovim/nvim-lspconfig/blob/master/lua/lspconfig/server_configurations/)
       to get started. Most configs are simple. For an extensive example see
       [texlab.lua](https://github.com/neovim/nvim-lspconfig/blob/master/lua/lspconfig/server_configurations/texlab.lua).
-
 3. Ask questions on our [Discourse](https://neovim.discourse.group/c/7-category/7) or in the [Neovim Matrix room](https://app.element.io/#/room/#neovim:matrix.org).
-
-You can also help out by testing [PRs with the `needs-testing`](https://github.com/neovim/nvim-lspconfig/issues?q=is%3Apr+is%3Aopen+label%3Aneeds-testing) label that affect language servers you use regularly.