docs: provide example for configuring LSP foldexpr (#31411)

Using the "supports_method" function with a client capability inside of
an LspAttach autocommand is the preferred method to do this, so we
should be showing users how to do it.

1 files changed, 16 insertions, 0 deletions

diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index a3791e15c3..b1a3316e3e 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/runtime/lua/vim/lsp.lua
@@ -1097,6 +1097,22 @@ function lsp.tagfunc(pattern, flags)
 end
 
 --- Provides an interface between the built-in client and a `foldexpr` function.
+---
+--- To use, check for the "textDocument/foldingRange" capability in an
+--- |LspAttach| autocommand. Example:
+---
+--- ```lua
+--- vim.api.nvim_create_autocommand('LspAttach', {
+---   callback = function(args)
+---     local client = vim.lsp.get_client_by_id(args.data.client_id)
+---     if client:supports_method('textDocument/foldingRange') then
+---       vim.wo.foldmethod = 'expr'
+---       vim.wo.foldexpr = 'v:lua.vim.lsp.foldexpr()'
+---     end
+---   end,
+--- })
+--- ```
+---
 ---@param lnum integer line number
 function lsp.foldexpr(lnum)
   return vim.lsp._folding_range.foldexpr(lnum)