docs: update mason-lspconfig.setup_handlers() docs & add some tests (#94)

3 files changed, 99 insertions, 23 deletions

diff --git a/doc/mason-lspconfig.txt b/doc/mason-lspconfig.txt
index b6c6b415..052c57ca 100644
--- a/doc/mason-lspconfig.txt
+++ b/doc/mason-lspconfig.txt
@@ -131,11 +131,30 @@ setup({config})
 
                                             *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.
+    Advanced feature ~
+        This is an advanced, opt-in, feature that require some careful reading
+        of the documentation.
 
-    {handlers} is a table where all values is a function with the signature
-    `function (server_name: string)`. It has the following structure:
+        The recommended method to set up servers with lspconfig is to do so by
+        following their guides, see |lspconfig-quickstart|.
+
+    Registers the provided {handlers}, to be called by mason when an installed
+    server supported by lspconfig is ready to be setup.
+
+    {handlers} is a table where the keys are the name of an lspconfig server,
+    and the values are the function to be called when that server is ready to
+    be set up (i.e. is installed).
+
+    You may also pass a default handler that will be called when no dedicated
+    handler is provided. This is done by providing a function without a key
+    (see example below).
+
+   NOTE: ~
+       The server names provided as keys are the lspconfig server names, not
+       mason's package names, so for example instead of "lua-language-server"
+       it's "sumneko_lua".
+
+    Example: ~
 
         require("mason-lspconfig").setup_handlers({
             -- The first entry (without a key) will be the default handler
@@ -145,12 +164,27 @@ setup_handlers({handlers})
                 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
+            end,
+            ["sumneko_lua"] = function ()
+                lspconfig.sumneko_lua.setup {
+                    settings = {
+                        Lua = {
+                            diagnostics = {
+                                globals = { "vim" }
+                            }
+                        }
+                    }
+                }
+            end,
         })
 
+    See also: ~
+        You may achieve similar behaviour by manually looping through the
+        installed servers (see |mason-lspconfig.get_installed_servers()|) and
+        setting each one up.
+
                                      *mason-lspconfig.get_installed_servers()*
 get_installed_servers()
     Returns the installed LSP servers supported by lspconfig.
diff --git a/lua/mason-lspconfig/init.lua b/lua/mason-lspconfig/init.lua
index e3c7cc93..659825ad 100644
--- a/lua/mason-lspconfig/init.lua
+++ b/lua/mason-lspconfig/init.lua
@@ -6,6 +6,7 @@ local settings = require "mason-lspconfig.settings"
 local server_mapping = require "mason-lspconfig.mappings.server"
 local path = require "mason-core.path"
 local registry = require "mason-registry"
+local notify = require "mason-core.notify"
 
 local M = {}
 
@@ -107,27 +108,22 @@ function M.setup(config)
     require "mason-lspconfig.api.command"
 end
 
----Register handlers that will be called when a server is ready to be set up (i.e. is installed).
----When this function is first called, the appropriate handler will be called for each installed server.
----When a new server is installed, the appropriate handler for that server will be called (this allows you for example to set up-new servers without restarting Neovim).
----The default handler is provided as the first value in the table argument.
----
----Example:
----```lua
----    require("mason-lspconfig").setup_handlers {
----        function (server_name)
----            -- default handler
----            require("lspconfig")[server_name].setup {}
----        end,
----        ["rust_analyzer"] = function ()
----            require("rust-tools").setup {}
----        end
----    }
----```
+---See `:h mason-lspconfig.setup_handlers()`
 ---@param handlers table<string, fun(server_name: string)>
 function M.setup_handlers(handlers)
     local default_handler = Optional.of_nilable(handlers[1])
 
+    _.each(function(handler)
+        if type(handler) == "string" and not server_mapping.lspconfig_to_package[handler] then
+            notify(
+                ("mason-lspconfig.setup_handlers: Received handler for unknown lspconfig server name: %s."):format(
+                    handler
+                ),
+                vim.log.levels.WARN
+            )
+        end
+    end, _.keys(handlers))
+
     ---@param pkg_name string
     local function get_server_name(pkg_name)
         return Optional.of_nilable(server_mapping.package_to_lspconfig[pkg_name])
diff --git a/tests/mason-lspconfig/setup_spec.lua b/tests/mason-lspconfig/setup_spec.lua
index 39795be4..28dbad40 100644
--- a/tests/mason-lspconfig/setup_spec.lua
+++ b/tests/mason-lspconfig/setup_spec.lua
@@ -1,4 +1,5 @@
 local match = require "luassert.match"
+local stub = require "luassert.stub"
 local spy = require "luassert.spy"
 
 local Pkg = require "mason-core.package"
@@ -43,3 +44,48 @@ describe("mason-lspconfig setup", function()
         })
     end)
 end)
+
+describe("mason-lspconfig setup_handlers", function()
+    server_mappings.lspconfig_to_package["dummylsp"] = "dummy"
+    server_mappings.package_to_lspconfig["dummy"] = "dummylsp"
+    filetype_mappings.dummylang = { "dummylsp" }
+
+    it("should call default handler", function()
+        stub(registry, "get_installed_package_names")
+        registry.get_installed_package_names.returns { "dummy" }
+        local default_handler = spy.new()
+
+        mason_lspconfig.setup_handlers { default_handler }
+
+        assert.spy(default_handler).was_called(1)
+        assert.spy(default_handler).was_called_with "dummylsp"
+    end)
+
+    it("should call dedicated handler", function()
+        stub(registry, "get_installed_package_names")
+        registry.get_installed_package_names.returns { "dummy" }
+        local dedicated_handler = spy.new()
+        local default_handler = spy.new()
+
+        mason_lspconfig.setup_handlers {
+            default_handler,
+            ["dummylsp"] = dedicated_handler,
+        }
+
+        assert.spy(default_handler).was_called(0)
+        assert.spy(dedicated_handler).was_called(1)
+        assert.spy(dedicated_handler).was_called_with "dummylsp"
+    end)
+
+    it("should print warning if registering handler for non-existent server name", function()
+        spy.on(vim, "notify")
+        mason_lspconfig.setup_handlers {
+            doesnt_exist_server = spy.new(),
+        }
+        assert.spy(vim.notify).was_called(1)
+        assert.spy(vim.notify).was_called_with(
+            "[mason.nvim] mason-lspconfig.setup_handlers: Received handler for unknown lspconfig server name: doesnt_exist_server.",
+            vim.log.levels.WARN
+        )
+    end)
+end)