doc #108

- mention :packadd
- more renames

1 files changed, 40 insertions, 46 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.