docs: func/expr options, misc #41102

runtime/lua/vim/_core/editor.lua

@@ -1217,7 +1217,7 @@ do
   --- Omnifunc for completing Lua values from the runtime Lua interpreter,
   --- similar to the builtin completion for the `:lua` command.
   ---
-  --- Activate using `set omnifunc=v:lua.vim.lua_omnifunc` in a Lua buffer.
+  --- Activate using `vim.bo.omnifunc = vim.lua_omnifunc` in a Lua buffer.
   --- @param find_start 1|0
   function vim.lua_omnifunc(find_start, _)
     if find_start == 1 then

runtime/lua/vim/_meta/options.gen.lua

@@ -811,14 +811,13 @@ vim.bo.channel = vim.o.channel
 --- Also used for Unicode conversion.
 --- Example:
 ---
---- ```vim
---- 	set charconvert=CharConvert()
---- 	fun CharConvert()
---- 	  system("recode "
---- 		\ .. v:charconvert_from .. ".." .. v:charconvert_to
---- 		\ .. " <" .. v:fname_in .. " >" .. v:fname_out)
---- 	  return v:shell_error
---- 	endfun
+--- ```lua
+--- 	vim.o.charconvert = function()
+--- 	  vim.fn.system(('recode %s..%s <%s >%s'):format(
+--- 	    vim.v.charconvert_from, vim.v.charconvert_to,
+--- 	    vim.v.fname_in, vim.v.fname_out))
+--- 	  return vim.v.shell_error
+--- 	end
 --- ```
 --- The related Vim variables are:
 --- 	v:charconvert_from	name of the current encoding
@@ -2655,20 +2654,20 @@ vim.go.fcs = vim.go.fillchars
 ---
 --- Examples:
 ---
---- ```vim
----     " Use glob()
----     func FindFuncGlob(cmdarg, cmdcomplete)
---- 	let pat = a:cmdcomplete ? $'{a:cmdarg}*' : a:cmdarg
---- 	return glob(pat, v:false, v:true)
----     endfunc
----     set findfunc=FindFuncGlob
+--- ```lua
+---     -- Use vim.fn.glob()
+---     vim.o.findfunc = function(cmdarg, cmdcomplete)
+---       local pat = cmdcomplete and (cmdarg .. '*') or cmdarg
+---       return vim.fn.glob(pat, false, true)
+---     end
 ---
----     " Use the 'git ls-files' output
----     func FindGitFiles(cmdarg, cmdcomplete)
---- 	let fnames = systemlist('git ls-files')
---- 	return fnames->filter('v:val =~? a:cmdarg')
----     endfunc
----     set findfunc=FindGitFiles
+---     -- Use the "git ls-files" output
+---     vim.o.findfunc = function(cmdarg, cmdcomplete)
+---       local fnames = vim.fn.systemlist('git ls-files')
+---       return vim.tbl_filter(function(v)
+---         return v:lower():find(cmdarg:lower(), 1, true) ~= nil
+---       end, fnames)
+---     end
 --- ```
 ---
 ---

runtime/lua/vim/fs.lua

@@ -191,9 +191,9 @@ end
 --- (default: `false`)
 --- @field follow? boolean
 ---
---- Expand "~" and "$" in {path} before scanning the directory.
---- (default: `true`)
---- @field normalize? boolean
+--- Do not expand special forms like "~" and "$" in {path}.
+--- (default: `false`)
+--- @field plain? boolean
 
 --- Gets an iterator over items found in `path` (normalized via |vim.fs.normalize()|).
 ---
@@ -210,7 +210,7 @@ end
 ---@since 10
 ---@param path (string) Directory to iterate over, normalized via |vim.fs.normalize()| unless
 ---            `opts.normalize=false`.
----@param opts? vim.fs.dir.Opts Optional keyword arguments:
+---@param opts? vim.fs.dir.Opts
 ---@return fun(): string?, string?, string? # Iterator over items in {path}, yielding (name, type, err):
 ---        - name: Basename of the item relative to {path}.
 ---        - type: One of: "file", "directory", "link", "fifo", "socket", "char", "block", "unknown".
@@ -224,9 +224,9 @@ function M.dir(path, opts)
   vim.validate('err', opts.err, 'boolean', true)
   vim.validate('follow', opts.follow, 'boolean', true)
   vim.validate('skip', opts.skip, 'function', true)
-  vim.validate('normalize', opts.normalize, 'boolean', true)
+  vim.validate('plain', opts.plain, 'boolean', true)
 
-  if opts.normalize ~= false then
+  if opts.plain ~= true then
     path = M.normalize(path)
   end
 

runtime/lua/vim/lsp.lua

@@ -1374,8 +1374,13 @@ end
 --- Provides an interface between the built-in client and a `formatexpr` function.
 ---
 --- Currently only supports a single client. This can be set via
---- `setlocal formatexpr=v:lua.vim.lsp.formatexpr()` or (more typically) in `on_attach`
---- via `vim.bo[bufnr].formatexpr = 'v:lua.vim.lsp.formatexpr(#{timeout_ms:250})'`.
+--- `vim.bo[bufnr].formatexpr = vim.lsp.formatexpr`, or with a wrapper to pass options:
+---
+--- ```lua
+--- vim.bo[bufnr].formatexpr = function()
+---   return vim.lsp.formatexpr({ timeout_ms = 250 })
+--- end
+--- ```
 ---
 ---@param opts? vim.lsp.formatexpr.Opts
 function lsp.formatexpr(opts)
@@ -1445,7 +1450,7 @@ end
 ---
 --- ```lua
 --- vim.o.foldmethod = 'expr'
---- vim.o.foldexpr = 'v:lua.vim.lsp.foldexpr()'
+--- vim.o.foldexpr = vim.lsp.foldexpr
 --- ```
 ---
 --- Or use it only when supported by checking for the "textDocument/foldingRange"
@@ -1454,14 +1459,14 @@ end
 --- ```lua
 --- vim.o.foldmethod = 'expr'
 --- -- Default to treesitter folding
---- vim.o.foldexpr = 'v:lua.vim.treesitter.foldexpr()'
+--- vim.o.foldexpr = vim.treesitter.foldexpr
 --- -- Prefer LSP folding if client supports it
 --- vim.api.nvim_create_autocmd('LspAttach', {
 ---   callback = function(ev)
 ---     local client = vim.lsp.get_client_by_id(ev.data.client_id)
 ---     if client:supports_method('textDocument/foldingRange') then
 ---       local win = vim.api.nvim_get_current_win()
----       vim.wo[win][0].foldexpr = 'v:lua.vim.lsp.foldexpr()'
+---       vim.wo[win][0].foldexpr = vim.lsp.foldexpr
 ---     end
 ---   end,
 --- })

runtime/lua/vim/treesitter.lua

@@ -502,7 +502,7 @@ end
 --- Returns the fold level for {lnum} in the current buffer. Can be set directly to 'foldexpr':
 ---
 --- ```lua
---- vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()'
+--- vim.wo.foldexpr = vim.treesitter.foldexpr
 --- ```
 ---
 ---@since 11