docs: add an entry about the setup-hook (#1873)

1 files changed, 22 insertions, 0 deletions

diff --git a/doc/lspconfig.txt b/doc/lspconfig.txt
index 3a79db0a..70339a8b 100644
--- a/doc/lspconfig.txt
+++ b/doc/lspconfig.txt
@@ -228,6 +228,28 @@ The global defaults for all servers can be overridden by extending the
 `setup {}` can additionally override these defaults in subsequent calls.
 
 ==============================================================================
+SETUP HOOK                                                *lspconfig-setup-hook*
+
+`lspconfig` will execute the `on_setup` hook for each setup call to a server after
+validating its configuration, and before attempting to launch the server
+itself. One typical usage is to allow ad-hoc substitution for any
+configuration entry, such as `cmd`.
+
+>
+  local lspconfig = require 'lspconfig'
+  lspconfig.util.on_setup = util.add_hook_before(lspconfig.util.on_setup, function(config)
+    if some_condition and config.name == "clangd" then
+      local custom_server_prefix = "/my/custom/server/prefix"
+      config.cmd = { custom_server_prefix .. "/bin/clangd" }
+    end
+  end)
+
+
+Note: This is primarily targeted at plugins developers, so make sure to use
+`util.add_hook_before()` as a wrapper instead of overriding the original function
+completely, to void breaking external integrations with lspconfig.
+
+==============================================================================
 SERVER CONFIGURATIONS                                 *lspconfig-configurations*
 
 See |lspconfig-all| for the complete list of language server configurations.