docs: add an entry about the setup-hook

[kylo252]

The on_setup hook is currently undocumented, and it should gain some attention after williamboman/nvim-lsp-installer#631

[mjlbach]

Maybe emphasize "this is principally for plugin developers, and overriding this without wrapping the original function may break external integrations with lspconfig"

[kylo252]

would it make sense to have this setting per-server instead of being global?

diff --git a/lua/lspconfig/util.lua b/lua/lspconfig/util.lua
index 3febafc..3e57fde 100644
--- a/lua/lspconfig/util.lua
+++ b/lua/lspconfig/util.lua
@@ -14,11 +14,9 @@ M.default_config = {
   init_options = vim.empty_dict(),
   handlers = {},
   autostart = true,
+  on_setup = nil
 }
 
--- global on_setup hook
-M.on_setup = nil

it could then be renamed to pre_init or something, if on_setup is ambiguous here I forgot that before_init exists, can we not use that instead?

[williamboman]

FWIW, I found use for this in my personal configs for making sure to apply a set of default configurations (primarily the ever so present on_attach and capabilities settings).

1. Register a hook for applying defaults
2. Call setup while only having to pass server specific settings:
   - https://github.com/williamboman/nvim-config/blob/9668609f2a52f3d4630c0cbb553e4be379035ed3/after/plugin/lsp/servers/pylsp.lua#L6)
   - https://github.com/williamboman/nvim-config/blob/9668609f2a52f3d4630c0cbb553e4be379035ed3/after/plugin/lsp/servers/jsonls.lua#L12-L6

[williamboman]

Did you perhaps mean to set the cmd? cmd_env is a table

Suggested change

	config.cmd_env = custom_server_prefix
	config.cmd = { custom_server_prefix }

[kylo252]

good catch!

[kylo252]

hopefully this new example makes sense!

FWIW, I found use for this in my personal configs for making sure to apply a set of default configurations (primarily the ever so present on_attach and capabilities settings).

I'm not sure if this is something that @mjlbach wants to advertise (?)

since he suggested the note about this targeting plugins devs, and one can get a somewhat similar result by overriding the global defaults :h lspconfig-global-defaults

[williamboman]

Ah TIL about global defaults 😅. I guess one difference is that with the hook approach you can make sure to merge settings, for example chaining function on_attach and on_new_config calls.