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 #1951

1 files changed, 8 insertions, 3 deletions

diff --git a/lua/lspconfig/server_configurations/clangd.lua b/lua/lspconfig/server_configurations/clangd.lua
index 0dbe2cfd..83cfc56d 100644
--- a/lua/lspconfig/server_configurations/clangd.lua
+++ b/lua/lspconfig/server_configurations/clangd.lua
@@ -61,9 +61,14 @@ return {
     description = [[
 https://clangd.llvm.org/installation.html
 
-**NOTE:** Clang >= 11 is recommended! See [this issue for more](https://github.com/neovim/nvim-lsp/issues/23).
-
-clangd relies on a [JSON compilation database](https://clang.llvm.org/docs/JSONCompilationDatabase.html) specified as compile_commands.json, see https://clangd.llvm.org/installation#compile_commandsjson
+- **NOTE:** Clang >= 11 is recommended! See [#23](https://github.com/neovim/nvim-lsp/issues/23).
+- If `compile_commands.json` lives in a build directory, you should
+  symlink it to the root of your source tree.
+  ```
+  ln -s ~/myproject/compile_commands.json ~/myproject/build/
+  ```
+- clangd relies on a [JSON compilation database](https://clang.llvm.org/docs/JSONCompilationDatabase.html)
+  specified as compile_commands.json, see https://clangd.llvm.org/installation#compile_commandsjson
 ]],
     default_config = {
       root_dir = [[