docs: misc #31996

4 files changed, 26 insertions, 23 deletions

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index af194aa70e..15cdd8fc79 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -1152,8 +1152,7 @@ function vim.api.nvim_eval(expr) end
 ---               the "highlights" key in {opts} is true. Each element of the array is a
 ---               |Dict| with these keys:
 ---     - start: (number) Byte index (0-based) of first character that uses the highlight.
----     - group: (string) Name of highlight group. May be removed in the future, use
----     `groups` instead.
+---     - group: (string) Deprecated. Use `groups` instead.
 ---     - groups: (array) Names of stacked highlight groups (highest priority last).
 function vim.api.nvim_eval_statusline(str, opts) end
 
diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua
index 9fa2e242c4..2d5975b977 100644
--- a/runtime/lua/vim/_meta/builtin.lua
+++ b/runtime/lua/vim/_meta/builtin.lua
@@ -223,12 +223,11 @@ function vim.schedule(fn) end
 ---     - If {callback} errors, the error is raised.
 function vim.wait(time, callback, interval, fast_only) end
 
---- Attach to |ui-events|, similar to |nvim_ui_attach()| but receive events
---- as Lua callback. Can be used to implement screen elements like
---- popupmenu or message handling in Lua.
+--- Subscribe to |ui-events|, similar to |nvim_ui_attach()| but receive events in a Lua callback.
+--- Used to implement screen elements like popupmenu or message handling in Lua.
 ---
---- {options} should be a dictionary-like table, where `ext_...` options should
---- be set to true to receive events for the respective external element.
+--- {options} is a dict with one or more `ext_…` |ui-option|s set to true to enable events for
+--- the respective UI element.
 ---
 --- {callback} receives event name plus additional parameters. See |ui-popupmenu|
 --- and the sections below for event format for respective events.
@@ -250,14 +249,14 @@ function vim.wait(time, callback, interval, fast_only) end
 --- ns = vim.api.nvim_create_namespace('my_fancy_pum')
 ---
 --- vim.ui_attach(ns, {ext_popupmenu=true}, function(event, ...)
----   if event == "popupmenu_show" then
+---   if event == 'popupmenu_show' then
 ---     local items, selected, row, col, grid = ...
----     print("display pum ", #items)
----   elseif event == "popupmenu_select" then
+---     print('display pum ', #items)
+---   elseif event == 'popupmenu_select' then
 ---     local selected = ...
----     print("selected", selected)
----   elseif event == "popupmenu_hide" then
----     print("FIN")
+---     print('selected', selected)
+---   elseif event == 'popupmenu_hide' then
+---     print('FIN')
 ---   end
 --- end)
 --- ```
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index 25cc3aae00..8df174a838 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/runtime/lua/vim/_meta/options.lua
@@ -4381,8 +4381,8 @@ vim.go.mousemodel = vim.o.mousemodel
 vim.go.mousem = vim.go.mousemodel
 
 --- When on, mouse move events are delivered to the input queue and are
---- available for mapping. The default, off, avoids the mouse movement
---- overhead except when needed.
+--- available for mapping `<MouseMove>`. The default, off, avoids the mouse
+--- movement overhead except when needed.
 --- Warning: Setting this option can make pending mappings to be aborted
 --- when the mouse is moved.
 ---
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index 4970a3023b..5504d577d6 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -899,12 +899,13 @@ function vim.fn.charidx(string, idx, countcc, utf16) end
 --- @return string
 function vim.fn.chdir(dir) end
 
---- Get the amount of indent for line {lnum} according the C
---- indenting rules, as with 'cindent'.
+--- Get the amount of indent for line {lnum} according the
+--- |C-indenting| rules, as with 'cindent'.
 --- The indent is counted in spaces, the value of 'tabstop' is
 --- relevant.  {lnum} is used just like in |getline()|.
 --- When {lnum} is invalid -1 is returned.
---- See |C-indenting|.
+---
+--- To get or set indent of lines in a string, see |vim.text.indent()|.
 ---
 --- @param lnum integer
 --- @return integer
@@ -4430,6 +4431,8 @@ function vim.fn.id(expr) end
 --- |getline()|.
 --- When {lnum} is invalid -1 is returned.
 ---
+--- To get or set indent of lines in a string, see |vim.text.indent()|.
+---
 --- @param lnum integer|string
 --- @return integer
 function vim.fn.indent(lnum) end
@@ -5335,9 +5338,8 @@ function vim.fn.map(expr1, expr2) end
 --- When {abbr} is there and it is |TRUE| use abbreviations
 --- instead of mappings.
 ---
---- When {dict} is there and it is |TRUE| return a dictionary
---- containing all the information of the mapping with the
---- following items:      *mapping-dict*
+--- When {dict} is |TRUE|, return a dictionary describing the
+--- mapping, with these items:    *mapping-dict*
 ---   "lhs"       The {lhs} of the mapping as it would be typed
 ---   "lhsraw"   The {lhs} of the mapping as raw bytes
 ---   "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate
@@ -5389,7 +5391,7 @@ function vim.fn.maparg(name, mode, abbr, dict) end
 --- @param mode string
 --- @param abbr boolean
 --- @param dict true
---- @return string|table<string,any>
+--- @return table<string,any>
 function vim.fn.maparg(name, mode, abbr, dict) end
 
 --- Check if there is a mapping that matches with {name} in mode
@@ -6821,6 +6823,7 @@ function vim.fn.prompt_getprompt(buf) end
 ---      endif
 ---    endfunc
 ---    call prompt_setcallback(bufnr(), function('s:TextEntered'))
+--- <
 ---
 --- @param buf integer|string
 --- @param expr string|function
@@ -9328,7 +9331,9 @@ function vim.fn.state(what) end
 function vim.fn.stdioopen(opts) end
 
 --- Returns |standard-path| locations of various default files and
---- directories.
+--- directories. The locations are driven by |base-directories|
+--- which you can configure via |$NVIM_APPNAME| or the `$XDG_…`
+--- environment variables.
 ---
 --- {what}       Type    Description ~
 --- cache        String  Cache directory: arbitrary temporary