docs: add docs for mason-lspconfig (#61)

3 files changed, 166 insertions, 2 deletions

diff --git a/README.md b/README.md
index 8ae53efe..aaea774e 100644
--- a/README.md
+++ b/README.md
@@ -24,6 +24,7 @@
 -   [Setup](#setup)
 -   [Commands](#commands)
 -   [Configuration](#configuration)
+-   [Extensions](#extensions)
 
 # Introduction
 
@@ -80,6 +81,8 @@ Plug "williamboman/mason.nvim", { 'branch': 'alpha' }
 require("mason").setup {}
 ```
 
+Refer to [extensions](#extensions) for extra, opt-in, functionality!
+
 Refer to the [Configuration](#configuration) section for information about which settings are available.
 
 # Commands
@@ -92,7 +95,8 @@ Refer to the [Configuration](#configuration) section for information about which
 
 # Configuration
 
-You may optionally configure certain behavior of `mason.nvim` when calling the `.setup()` function.
+You may optionally configure certain behavior of `mason.nvim` when calling the `.setup()` function. Refer to the
+[default configuration](#default-configuration) for a list of all available settings.
 
 Example:
 
@@ -108,6 +112,8 @@ require("mason").setup({
 })
 ```
 
+## Default configuration
+
 ```lua
 local DEFAULT_SETTINGS = {
     ui = {
@@ -174,3 +180,21 @@ local DEFAULT_SETTINGS = {
     },
 }
 ```
+
+# Extensions
+
+## `mason-lspconfig`
+
+`mason-lspconfig` is a native extension to `mason.nvim` that ships with
+`mason.nvim`. It bridges `mason.nvim` with the `lspconfig` plugin in order to
+make it easier to use the both plugins together.
+
+It is recommended to use this extension if you use `lspconfig`. To use this extension, make sure to set it up after
+`mason.nvim`, like so:
+
+```lua
+require("mason").setup()
+require("mason-lspconfig").setup()
+```
+
+For more documentation, see [`:h mason-lspconfig`](./doc/mason-lspconfig.txt).
diff --git a/doc/mason-lspconfig.txt b/doc/mason-lspconfig.txt
new file mode 100644
index 00000000..e200067a
--- /dev/null
+++ b/doc/mason-lspconfig.txt
@@ -0,0 +1,140 @@
+*mason-lspconfig*
+
+Minimum version of neovim: 0.7.0
+
+Author: William Boman
+
+==============================================================================
+INTRODUCTION                                    *mason-lspconfig-introduction*
+
+`mason-lspconfig` is a native extension to `mason.nvim` that ships with
+`mason.nvim`. It bridges `mason.nvim` with the `lspconfig` plugin in order to
+make it easier to use the both plugins together.
+
+It is recommended to use this extension if you use `lspconfig`.
+
+Among other things, it provides convenience APIs that allow you to use
+mason.nvim as the main control for dynamically setting up installed servers on
+an ad-hoc basis. It also provides extra commands such as `:LspInstall` that
+for example allow you to install servers for the current 'filetype'. Lastly,
+it also registers a setup hook with `lspconfig` that ensures servers installed
+with `mason.nvim` are set up with the necessary extra configuration (however,
+this only applies to a few select servers!).
+
+`lspconfig`: https://github.com/neovim/nvim-lspconfig
+
+==============================================================================
+REQUIREMENTS                                    *mason-lspconfig-requirements*
+
+`mason-lspconfig` requires `lspconfig` to be installed. Note that `lspconfig`
+needs to be available when setting up `mason-lspconfig` - so if you lazy load
+either plugin make sure `lspconfig` is not loaded after `mason-lspconfig`.
+
+Also, make sure not to set up any servers via `lspconfig` _before_ calling
+`mason-lspconfig`'s setup function.
+
+==============================================================================
+QUICK START                                       *mason-lspconfig-quickstart*
+
+The only thing needed to enable the `mason-lspconfig` plugin is to make sure
+to call the `setup()` function:
+
+    require("mason").setup()
+    require("mason-lspconfig").setup()
+
+==============================================================================
+COMMANDS                                            *mason-lspconfig-commands*
+
+                                                                 *:LspInstall*
+:LspInstall [<server>...]
+
+Installs the provided servers. This command only accepts servers that have a
+corresponding server configuration in `lspconfig`.
+
+You may also provide a language, like `:LspInstall typescript`. This will
+prompt you with a selection of all available servers for that given language.
+
+When the command is ran without any arguments, the currently active buffer's
+'filetype' will be used to identify relevant servers, and you will be prompted
+with a selection of all suggested servers.
+
+                                                               *:LspUninstall*
+:LspUninstall <server> ...
+
+Uninstalls the provided servers.
+
+==============================================================================
+SETTINGS                                            *mason-lspconfig-settings*
+
+You can configure certain behavior of `mason-lspconfig` when calling the
+`.setup()` function.
+
+Refer to |mason-lspconfig-default-settings| for all available settings.
+
+Example:
+
+    require("mason-lspconfig").setup({
+        ensure_installed = { "rust_analyzer", "tsserver" }
+    })
+
+                                            *mason-lspconfig-default-settings*
+
+    local DEFAULT_SETTINGS = {
+        -- A list of servers to automatically install if they're not already installed. Example: { "rust-analyzer@nightly", "sumneko_lua" }
+        -- This setting has no relation with the `automatic_installation` setting.
+        ensure_installed = {},
+
+        -- Whether servers that are set up (via lspconfig) should be automatically installed if they're not already installed.
+        -- This setting has no relation with the `ensure_installed` setting.
+        -- Can either be:
+        --   - false: Servers are not automatically installed.
+        --   - true: All servers set up via lspconfig are automatically installed.
+        --   - { exclude: string[] }: All servers set up via lspconfig, except the ones provided in the list, are automatically installed.
+        --       Example: automatic_installation = { exclude = { "rust_analyzer", "solargraph" } }
+        automatic_installation = false,
+    }
+
+==============================================================================
+AUTOMATIC SERVER SETUP
+                                      *mason-lspconfig-automatic-server-setup*
+
+`mason-lspconfig` provides opt-in functionality that allow you to
+automatically set up LSP servers installed with `mason.nvim`, without having
+to edit your Neovim configuration for every single server you want to use.
+This is also convenient if you want to use `mason.nvim` as the control for
+which servers to set up. It also makes it possible to set up newly installed
+servers without having to restart Neovim!
+
+Refer to |mason-lspconfig.setup_handlers()| for more information!
+
+==============================================================================
+Lua module: mason-lspconfig
+
+                                                     *mason-lspconfig.setup()*
+setup({config})
+    Sets up mason with the provided {config} (see |mason-lspconfig-settings|).
+
+                                            *mason-lspconfig.setup_handlers()*
+setup_handlers({handlers})
+    Registers the provided {handlers}, to be called by mason when a server is
+    ready to be set up.
+
+    {handlers} is a table where all values is a function with the signature
+    `function (server_name: string)`. It has the following structure:
+
+        require("mason-lspconfig").setup_handlers({
+            function (server_name) -- default handler (optional)
+                -- The first entry (without a key) will be the default handler
+                -- and will be called for each installed server that doesn't have
+                -- a dedicated handler.
+                require("lspconfig")[server_name].setup {}
+            end,
+            -- Next, you can provide targeted overrides for specific servers.
+            -- For example, a handler override for the `rust_analyzer`:
+            ["rust_analyzer"] = function ()
+                require("rust-tools").setup {}
+            end
+        })
+
+
+ vim:tw=78:ft=help:norl:expandtab:sw=4
diff --git a/doc/mason.txt b/doc/mason.txt
index 9ae43be1..3ddf08cf 100644
--- a/doc/mason.txt
+++ b/doc/mason.txt
@@ -241,6 +241,6 @@ Lua module: mason
 
                                                                *mason.setup()*
 setup({config})
-        Sets up mason with the provided {config} (see |mason-settings|).
+    Sets up mason with the provided {config} (see |mason-settings|).
 
  vim:tw=78:ft=help:norl:expandtab:sw=4