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.

2 files changed, 29 insertions, 0 deletions

diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index f7157df0f2..e311831bd3 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -720,6 +720,19 @@ foldexpr({lnum})                                          *vim.lsp.foldexpr()*
     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,
+        })
+<
+
     Parameters: ~
       • {lnum}  (`integer`) line number
 
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)