doc #108

- mention :packadd
- more renames

4 files changed, 63 insertions, 59 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3099bb85..50e196c9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,56 +1,46 @@
 # Requirements
 
-- Neovim :P
-- docgen requires a unix system.
-- luacheck for linting Lua code. ([Install](https://github.com/mpeterv/luacheck#installation))
+- [Neovim](https://neovim.io/) :P
+- `scripts/docgen.lua` expects a unix system.
+- [luacheck](https://github.com/mpeterv/luacheck#installation) for the lint job.
 
 # Generating docs
 
-> NOTE: Github Actions automatically generates the docs, so only modify
-> `README_template.md` or the `docs` object on the server config!
-> **DO NOT MODIFY `README.md` DIRECTLY**
+> Note: Github Actions automatically generates the docs, so only modify
+> `README_template.md` or the `docs` object on the server config.
+> Don't modify `README.md` directly.
 
-To preview the generated `README.md` locally, source `scripts/docgen.lua` from
-`nvim` (e.g. with `:luafile`):
+To preview the generated `README.md` locally, run `scripts/docgen.lua` from
+`nvim` (from the project root):
 
     nvim -R -Es +'set rtp+=$PWD' +'luafile scripts/docgen.lua'
 
-It **must** be run from the `.git`/project root. (TODO: try to find the `.git`
-root with one of our `util.*` functions?)
+# Configs
 
-# configs
+The `configs` module is a singleton where configs are defined. In `vim.validate`
+parlance here is the "spec":
 
-configs has a `__newindex` metamethod which validates and creates
-an object containing `setup()`, which can then be retrieved and modified.
+    configs.SERVER_NAME = {
+      default_config = {'t'};
+      on_new_config = {'f', true};
+      on_attach = {'f', true};
+      commands = {'t', true};
+      docs = {'t', true};
+    }
+    docs = {
+      description = {'s', true};
+      default_config = {'t', true};
+    }
 
-In `vim.validate` parlance, this is the "spec":
-
-```
-configs.SERVER_NAME = {
-  default_config = {'t'};
-  on_new_config = {'f', true};
-  on_attach = {'f', true};
-  commands = {'t', true};
-  docs = {'t', true};
-}
-docs = {
-  description = {'s', true};
-  default_config = {'t', true};
-}
-```
-
-- Keys of the `docs.default_config` table match those of
+- Keys in `docs.default_config` match those of
   `configs.SERVER_NAME.default_config`, and can be used to specify custom
   documentation. This is useful for functions, whose docs cannot be easily
   auto-generated.
-- The `commands` object is a table of `name:definition` key:value pairs, where
-  `definition` is a list whose first value is a function implementing the
-  command. The other table values are either array values which will be formed
-  into flags for the command or special keys like `description`.
-
-Example:
-
-```
+- `commands` is a map of `name:definition` key:value pairs, where `definition`
+  is a list whose first value is a function implementing the command and the
+  rest are either array values which will be formed into flags for the command
+  or special keys like `description`. Example:
+  ```
   commands = {
     TexlabBuild = {
       function()
@@ -60,11 +50,15 @@ Example:
       description = "Build the current buffer";
     };
   };
-```
+  ```
+
+The `configs.__newindex` metamethod consumes the config definition and returns
+an object with a `setup()` method, to be invoked by users:
 
+    require'nvim_lsp'.SERVER_NAME.setup{}
 
-After you create `configs.SERVER_NAME`, you may add arbitrary
-language-specific functions to it if necessary.
+After you set `configs.SERVER_NAME` you can add arbitrary language-specific
+functions to it if necessary.
 
 Example:
 
@@ -72,10 +66,10 @@ Example:
 
 Finally, add a `require 'nvim_lsp/SERVER_NAME'` line to `lua/nvim_lsp.lua`.
 
-# Auto-installation
+## Auto-install
 
-Configs may optionally provide `install()` and `install_info()` functions.
-This will be recognized by `:LspInstall` and `:LspInstallInfo`.
+Configs may optionally provide `install()` and `install_info()` functions. This
+will be discovered by `:LspInstall` and `:LspInstallInfo`.
 
 `function install()` is the signature and it is expected that it will create
 any data in `util.base_install_dir/{server_name}`.
@@ -84,5 +78,5 @@ any data in `util.base_install_dir/{server_name}`.
 which indicates the current status of installation (if it is installed by us).
 It can contain any other additional data that the user may find useful.
 
-The helper function `util.npm_installer` can be used for lsps which are installed
-with `npm`. See `elmls.lua`, `tsserver.lua`, or `bashls.lua` for examples.
+Function `util.npm_installer()` can be used for`npm`-installable language
+servers. See `elmls.lua`, `tsserver.lua`, `bashls.lua` for examples.
diff --git a/README.md b/README.md
index cb610bd7..e551ddc9 100644
--- a/README.md
+++ b/README.md
@@ -29,12 +29,16 @@ Help us create configs for *all the LSPs!*
   ```
   :Plug 'neovim/nvim-lsp'
   ```
+- Call `:packadd nvim-lsp` in your config if you installed nvim-lsp to
+  'packpath' or if you use a package manager such as minpac.
+
 ## Usage
 
 Each config provides a `setup()` function, to initialize the server with
 reasonable defaults and some server-specific things like commands or different
 diagnostics.
 
+    vim.api.nvim_command('packadd nvim-lsp')
     require'nvim_lsp'.<config>.setup{name=…, settings = {…}, …}
 
 Find the [config](#configurations) for your language, then paste the example
@@ -49,6 +53,7 @@ config provides `nvim_lsp.texlab.buf_build({bufnr})`.
 To use the defaults, just call `setup()` with an empty `config` parameter.
 For the `gopls` config, that would be:
 
+    vim.api.nvim_command('packadd nvim-lsp')
     require'nvim_lsp'.gopls.setup{}
 
 ### Example: override some defaults
diff --git a/lua/nvim_lsp/configs.lua b/lua/nvim_lsp/configs.lua
index 7deadf1e..7733bf42 100644
--- a/lua/nvim_lsp/configs.lua
+++ b/lua/nvim_lsp/configs.lua
@@ -5,16 +5,16 @@ local tbl_extend = vim.tbl_extend
 local configs = {}
 
 
-function configs.__newindex(t, config_name, config_definition)
+function configs.__newindex(t, config_name, config_def)
   validate {
     name = {config_name, 's'};
-    default_config = {config_definition.default_config, 't'};
-    on_new_config = {config_definition.on_new_config, 'f', true};
-    on_attach = {config_definition.on_attach, 'f', true};
-    commands = {config_definition.commands, 't', true};
+    default_config = {config_def.default_config, 't'};
+    on_new_config = {config_def.on_new_config, 'f', true};
+    on_attach = {config_def.on_attach, 'f', true};
+    commands = {config_def.commands, 't', true};
   }
-  if config_definition.commands then
-    for k, v in pairs(config_definition.commands) do
+  if config_def.commands then
+    for k, v in pairs(config_def.commands) do
       validate {
         ['command.name'] = {k, 's'};
         ['command.fn'] = {v[1], 'f'};
@@ -24,7 +24,7 @@ function configs.__newindex(t, config_name, config_definition)
 
   local M = {}
 
-  local default_config = tbl_extend("keep", config_definition.default_config, {
+  local default_config = tbl_extend("keep", config_def.default_config, {
     log_level = lsp.protocol.MessageType.Warning;
     settings = {};
     init_options = vim.empty_dict();
@@ -110,8 +110,8 @@ function configs.__newindex(t, config_name, config_definition)
       })
 
       add_callbacks(new_config)
-      if config_definition.on_new_config then
-        pcall(config_definition.on_new_config, new_config)
+      if config_def.on_new_config then
+        pcall(config_def.on_new_config, new_config)
       end
       if config.on_new_config then
         pcall(config.on_new_config, new_config)
@@ -166,15 +166,15 @@ function configs.__newindex(t, config_name, config_definition)
     if client.config._on_attach then
       client.config._on_attach(client)
     end
-    if config_definition.commands then
+    if config_def.commands then
       -- Create the module commands
       util.create_module_commands(config_name, M.commands)
     end
   end
 
-  M.commands = config_definition.commands
+  M.commands = config_def.commands
   M.name = config_name
-  M.document_config = config_definition
+  M.document_config = config_def
 
   rawset(t, config_name, M)
 
diff --git a/scripts/README_template.md b/scripts/README_template.md
index 8a0f8145..044fd4b3 100644
--- a/scripts/README_template.md
+++ b/scripts/README_template.md
@@ -29,12 +29,16 @@ Help us create configs for *all the LSPs!*
   ```
   :Plug 'neovim/nvim-lsp'
   ```
+- Call `:packadd nvim-lsp` in your vimrc if you installed nvim-lsp to
+  `'packpath'` or if you use a package manager such as minpac.
+
 ## Usage
 
 Each config provides a `setup()` function, to initialize the server with
 reasonable defaults and some server-specific things like commands or different
 diagnostics.
 
+    vim.cmd('packadd nvim-lsp')
     require'nvim_lsp'.<config>.setup{name=…, settings = {…}, …}
 
 Find the [config](#configurations) for your language, then paste the example
@@ -49,6 +53,7 @@ config provides `nvim_lsp.texlab.buf_build({bufnr})`.
 To use the defaults, just call `setup()` with an empty `config` parameter.
 For the `gopls` config, that would be:
 
+    vim.cmd('packadd nvim-lsp')
     require'nvim_lsp'.gopls.setup{}
 
 ### Example: override some defaults