docs: misc #31867

16 files changed, 155 insertions, 118 deletions

diff --git a/.github/workflows/vim_patches.yml b/.github/workflows/vim_patches.yml
index b0be01089f..5154565def 100644
--- a/.github/workflows/vim_patches.yml
+++ b/.github/workflows/vim_patches.yml
@@ -43,7 +43,7 @@ jobs:
         id: update-version
         run: |
           git checkout -b ${VERSION_BRANCH}
-          nvim -V1 -es -i NONE +'luafile scripts/vimpatch.lua' +q
+          nvim -l scripts/vimpatch.lua
           printf 'NEW_PATCHES=%s\n' $([ -z "$(git diff)" ]; echo $?) >> $GITHUB_OUTPUT
 
       - name: Automatic PR
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 852037bb34..9e84dd40ac 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -654,20 +654,22 @@ nvim_del_var({name})                                          *nvim_del_var()*
       • {name}  Variable name
 
 nvim_echo({chunks}, {history}, {opts})                           *nvim_echo()*
-    Echo a message.
+    Prints a message given by a list of `[text, hl_group]` "chunks".
+
+    Example: >lua
+        vim.api.nvim_echo({ { 'chunk1-line1\nchunk1-line2\n' }, { 'chunk2-line1' } }, true, {})
+<
 
     Parameters: ~
-      • {chunks}   A list of `[text, hl_group]` arrays, each representing a
-                   text chunk with specified highlight group name or ID.
-                   `hl_group` element can be omitted for no highlight.
+      • {chunks}   List of `[text, hl_group]` pairs, where each is a `text`
+                   string highlighted by the (optional) name or ID `hl_group`.
       • {history}  if true, add to |message-history|.
       • {opts}     Optional parameters.
-                   • err: Treat the message like |:echoerr|. Omitted `hlgroup`
-                     uses |hl-ErrorMsg| instead.
-                   • verbose: Message is printed as a result of 'verbose'
-                     option. If Nvim was invoked with -V3log_file, the message
-                     will be redirected to the log_file and suppressed from
-                     direct output.
+                   • err: Treat the message like `:echoerr`. Sets `hl_group`
+                     to |hl-ErrorMsg| by default.
+                   • verbose: Message is controlled by the 'verbose' option.
+                     Nvim invoked with `-V3log` will write the message to the
+                     "log" file instead of standard output.
 
 nvim_eval_statusline({str}, {opts})                   *nvim_eval_statusline()*
     Evaluates statusline string.
@@ -760,6 +762,8 @@ nvim_get_api_info()                                      *nvim_get_api_info()*
 nvim_get_chan_info({chan})                              *nvim_get_chan_info()*
     Gets information about a channel.
 
+    See |nvim_list_uis()| for an example of how to get channel info.
+
     Parameters: ~
       • {chan}  channel_id, or 0 for current channel
 
@@ -781,7 +785,7 @@ nvim_get_chan_info({chan})                              *nvim_get_chan_info()*
           present if a pty is used (e.g. for conpty on Windows).
         • "buffer" (optional) Buffer connected to |terminal| instance.
         • "client" (optional) Info about the peer (client on the other end of
-          the RPC channel), which it provided via |nvim_set_client_info()|.
+          the channel), as set by |nvim_set_client_info()|.
 
 nvim_get_color_by_name({name})                      *nvim_get_color_by_name()*
     Returns the 24-bit RGB value of a |nvim_get_color_map()| color name or
@@ -1064,6 +1068,12 @@ nvim_list_tabpages()                                    *nvim_list_tabpages()*
 nvim_list_uis()                                              *nvim_list_uis()*
     Gets a list of dictionaries representing attached UIs.
 
+    Example: The Nvim builtin |TUI| sets its channel info as described in
+    |startup-tui|. In particular, it sets `client.name` to "nvim-tui". So you
+    can check if the TUI is running by inspecting the client name of each UI: >lua
+        vim.print(vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan).client.name)
+<
+
     Return: ~
         Array of UI dictionaries, each with these keys:
         • "height" Requested height of the UI
@@ -1112,7 +1122,7 @@ nvim_open_term({buffer}, {opts})                            *nvim_open_term()*
 
     Example: this `TermHl` command can be used to display and highlight raw
     ANSI termcodes, so you can use Nvim as a "scrollback pager" (for terminals
-    like kitty):                                   *terminal-scrollback-pager* >lua
+    like kitty):                     *ansi-colorize* *terminal-scrollback-pager* >lua
         vim.api.nvim_create_user_command('TermHl', function()
           local b = vim.api.nvim_create_buf(false, true)
           local chan = vim.api.nvim_open_term(b, {})
@@ -1237,25 +1247,23 @@ nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts})
 
                                                       *nvim_set_client_info()*
 nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
-    Self-identifies the client.
+    Self-identifies the client. Sets the `client` object returned by
+    |nvim_get_chan_info()|.
 
-    The client/plugin/application should call this after connecting, to
-    provide hints about its identity and purpose, for debugging and
-    orchestration.
+    Clients should call this just after connecting, to provide hints for
+    debugging and orchestration. (Note: Something is better than nothing!
+    Fields are optional, but at least set `name`.)
 
     Can be called more than once; the caller should merge old info if
     appropriate. Example: library first identifies the channel, then a plugin
     using that library later identifies itself.
 
-    Note: ~
-      • "Something is better than nothing". You don't need to include all the
-        fields.
-
     Attributes: ~
         |RPC| only
 
     Parameters: ~
-      • {name}        Short name for the connected client
+      • {name}        Client short-name. Sets the `client.name` field of
+                      |nvim_get_chan_info()|.
       • {version}     Dict describing the version, with these (optional) keys:
                       • "major" major version (defaults to 0 if not set, for
                         no release yet)
diff --git a/runtime/doc/health.txt b/runtime/doc/health.txt
index bca145bd8e..3d37b88321 100644
--- a/runtime/doc/health.txt
+++ b/runtime/doc/health.txt
@@ -21,18 +21,7 @@ To run all healthchecks, use: >vim
 <
 Plugin authors are encouraged to write new healthchecks. |health-dev|
 
-                                                                    *g:health*
-g:health  This global variable controls the behavior and appearance of the
-          `health` floating window. It should be a dictionary containing the
-          following optional keys:
-          - `style`: string? Determines the display style of the `health` window.
-                            Set to `'float'` to enable a floating window. Other
-                            styles are not currently supported.
-
-          Example: >lua
-            vim.g.health = { style = 'float' }
-
-Commands                                                     *health-commands*
+COMMANDS                                                     *health-commands*
 
                                                            *:che* *:checkhealth*
 :che[ckhealth]  Run all healthchecks.
@@ -60,6 +49,23 @@ Commands                                                     *health-commands*
                         :checkhealth vim*
 <
 
+USAGE                                                           *health-usage*
+
+Local mappings in the healthcheck buffer:
+
+q               Closes the window.
+
+Global configuration:
+
+                                                                    *g:health*
+g:health  Dictionary with the following optional keys:
+          - `style` (`'float'|nil`) Set to "float" to display :checkhealth in
+          a floating window instead of the default behavior.
+
+          Example: >lua
+            vim.g.health = { style = 'float' }
+
+--------------------------------------------------------------------------------
 Create a healthcheck                                              *health-dev*
 
 Healthchecks are functions that check the user environment, configuration, or
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 6386240f07..9df9bc3ab5 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1505,7 +1505,7 @@ vim.wo[{winid}][{bufnr}]                                              *vim.wo*
 Lua module: vim                                                      *lua-vim*
 
 vim.cmd({command})                                                 *vim.cmd()*
-    Executes Vim script commands.
+    Executes Vimscript (|Ex-commands|).
 
     Note that `vim.cmd` can be indexed with a command name to return a
     callable function to the command.
@@ -1539,9 +1539,9 @@ vim.cmd({command})                                                 *vim.cmd()*
 
     Parameters: ~
       • {command}  (`string|table`) Command(s) to execute. If a string,
-                   executes multiple lines of Vim script at once. In this
-                   case, it is an alias to |nvim_exec2()|, where `opts.output`
-                   is set to false. Thus it works identical to |:source|. If a
+                   executes multiple lines of Vimscript at once. In this case,
+                   it is an alias to |nvim_exec2()|, where `opts.output` is
+                   set to false. Thus it works identical to |:source|. If a
                    table, executes a single command. In this case, it is an
                    alias to |nvim_cmd()| where `opts` is empty.
 
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index e1824e068d..181ae317e1 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -221,6 +221,7 @@ DIAGNOSTICS
 
 EDITOR
 
+• Use |yxx| in :help docs to execute Lua and Vimscript code examples.
 • Improved |paste| handling for redo (dot-repeat) and macros (|recording|):
   • Redoing a large paste is significantly faster and ignores 'autoindent'.
   • Replaying a macro with |@| also replays pasted text.
@@ -276,7 +277,6 @@ LUA
   supporting two new parameters, `encoding` and `strict_indexing`.
 • |vim.json.encode()| has an option to enable forward slash escaping
 • |vim.fs.abspath()| converts paths to absolute paths.
-• Lua and vimscript code examples in docs can now be run using `yxx`.
 
 OPTIONS
 
@@ -362,8 +362,8 @@ UI
 • |vim.diagnostic.setqflist()| updates an existing quickfix list with the
   given title if found
 • |ui-messages| content chunks now also contain the highlight group ID.
-• |:checkhealth| can be display in a floating window and controlled by
-  the |g:health| variable.
+• |:checkhealth| can display in a floating window, controlled by the
+  |g:health| variable.
 
 ==============================================================================
 CHANGED FEATURES                                                 *news-changed*
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index 0bfbea75fb..c0254c3fa1 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -164,8 +164,7 @@ argument.
 		you can overwrite a file by adding an exclamation mark to
 		the Ex command, as in ":w!".  The 'readonly' option can be
 		reset with ":set noro" (see the options chapter, |options|).
-		Subsequent edits will not be done in readonly mode.  Calling
-		the executable "view" has the same effect as the -R argument.
+		Subsequent edits will not be done in readonly mode.
 		The 'updatecount' option will be set to 10000, meaning that
 		the swap file will not be updated automatically very often.
 		See |-M| for disallowing modifications.
@@ -226,7 +225,8 @@ argument.
 		arguments. The {script} name is stored at `_G.arg[0]`.
 
 		Sets 'verbose' to 1 (like "-V1"), so Lua `print()` writes to
-		output.
+		output, as well as other message-emitting functions like
+		|:echo|.
 		If {script} prints messages and doesn't cause Nvim to exit,
 		Nvim ensures output ends with a newline.
 
@@ -288,21 +288,18 @@ argument.
 		command from a script. |debug-mode|
 
 							*-n*
--n		No |swap-file| will be used.  Recovery after a crash will be
-		impossible.  Handy if you want to view or edit a file on a
-		very slow medium (e.g., a floppy).
-		Can also be done with ":set updatecount=0".  You can switch it
-		on again by setting the 'updatecount' option to some value,
-		e.g., ":set uc=100".
-		'updatecount' is set to 0 AFTER executing commands from a
-		vimrc file, but before the GUI initializations.  Thus it
-		overrides a setting for 'updatecount' in a vimrc file, but not
-		in a gvimrc file.  See |startup|.
-		When you want to reduce accesses to the disk (e.g., for a
-		laptop), don't use "-n", but set 'updatetime' and
-		'updatecount' to very big numbers, and type ":preserve" when
-		you want to save your work.  This way you keep the possibility
-		for crash recovery.
+-n		Disables |swap-file| by setting 'updatecount' to 0 (after
+		executing any |vimrc|).  Recovery after a crash will be
+		impossible.  Improves peformance when working with a file on
+		a very slow medium (usb drive, network share).
+
+		Enable it again by setting 'updatecount' to some value, e.g.
+		":set updatecount=100".
+
+		To reduce accesses to the disk, don't use "-n", but set
+		'updatetime' and 'updatecount' to very big numbers, and type
+		":preserve" when you want to save your work.  This way you
+		keep the possibility for crash recovery.
 
 							*-o*
 -o[N]		Open N windows, split horizontally.  If [N] is not given,
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index a92ddf33e6..d690460f77 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -423,8 +423,11 @@ TUI:
 <
                         *'term'* *E529* *E530* *E531*
 - 'term' reflects the terminal type derived from |$TERM| and other environment
-  checks.  For debugging only; not reliable during startup. >vim
-          :echo &term
+  checks.  Use `:echo &term` to get its value. For debugging only; not
+  reliable during startup.
+  - Note: If you want to detect when Nvim is running in a terminal, use
+    `has('gui_running')` |has()| or see |nvim_list_uis()| for an example of
+    how to inspect the UI channel.
 - "builtin_x" means one of the |builtin-terms| was chosen, because the expected
   terminfo file was not found on the system.
 - Nvim will use 256-colour capability on Linux virtual terminals.  Vim uses
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 66815a967e..d4e6280b06 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -391,7 +391,7 @@ end
 
 local VIM_CMD_ARG_MAX = 20
 
---- Executes Vim script commands.
+--- Executes Vimscript (|Ex-commands|).
 ---
 --- Note that `vim.cmd` can be indexed with a command name to return a callable function to the
 --- command.
@@ -426,7 +426,7 @@ local VIM_CMD_ARG_MAX = 20
 --- ```
 ---
 ---@param command string|table Command(s) to execute.
----                            If a string, executes multiple lines of Vim script at once. In this
+---                            If a string, executes multiple lines of Vimscript at once. In this
 ---                            case, it is an alias to |nvim_exec2()|, where `opts.output` is set
 ---                            to false. Thus it works identical to |:source|.
 ---                            If a table, executes a single command. In this case, it is an alias
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index f6d8153c27..b5d8a0937d 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -1097,18 +1097,20 @@ function vim.api.nvim_del_user_command(name) end
 --- @param name string Variable name
 function vim.api.nvim_del_var(name) end
 
---- Echo a message.
+--- Prints a message given by a list of `[text, hl_group]` "chunks".
 ---
---- @param chunks any[] A list of `[text, hl_group]` arrays, each representing a
---- text chunk with specified highlight group name or ID.
---- `hl_group` element can be omitted for no highlight.
+--- Example:
+--- ```lua
+--- vim.api.nvim_echo({ { 'chunk1-line1\nchunk1-line2\n' }, { 'chunk2-line1' } }, true, {})
+--- ```
+---
+--- @param chunks any[] List of `[text, hl_group]` pairs, where each is a `text` string highlighted by
+--- the (optional) name or ID `hl_group`.
 --- @param history boolean if true, add to `message-history`.
 --- @param opts vim.api.keyset.echo_opts Optional parameters.
---- - err: Treat the message like `:echoerr`. Omitted `hlgroup`
----   uses `hl-ErrorMsg` instead.
---- - verbose: Message is printed as a result of 'verbose' option.
----   If Nvim was invoked with -V3log_file, the message will be
----   redirected to the log_file and suppressed from direct output.
+--- - err: Treat the message like `:echoerr`. Sets `hl_group` to `hl-ErrorMsg` by default.
+--- - verbose: Message is controlled by the 'verbose' option. Nvim invoked with `-V3log`
+---   will write the message to the "log" file instead of standard output.
 function vim.api.nvim_echo(chunks, history, opts) end
 
 --- @deprecated
@@ -1276,6 +1278,8 @@ function vim.api.nvim_get_autocmds(opts) end
 
 --- Gets information about a channel.
 ---
+--- See `nvim_list_uis()` for an example of how to get channel info.
+---
 --- @param chan integer channel_id, or 0 for current channel
 --- @return table<string,any> # Channel info dict with these keys:
 --- - "id"       Channel id.
@@ -1293,8 +1297,8 @@ function vim.api.nvim_get_autocmds(opts) end
 ---              "/dev/pts/1". If unknown, the key will still be present if a pty is used (e.g.
 ---              for conpty on Windows).
 --- -  "buffer"  (optional) Buffer connected to |terminal| instance.
---- -  "client"  (optional) Info about the peer (client on the other end of the RPC channel),
----              which it provided via |nvim_set_client_info()|.
+--- -  "client"  (optional) Info about the peer (client on the other end of the channel), as set
+---              by |nvim_set_client_info()|.
 ---
 function vim.api.nvim_get_chan_info(chan) end
 
@@ -1616,6 +1620,14 @@ function vim.api.nvim_list_tabpages() end
 
 --- Gets a list of dictionaries representing attached UIs.
 ---
+--- Example: The Nvim builtin `TUI` sets its channel info as described in `startup-tui`. In
+--- particular, it sets `client.name` to "nvim-tui". So you can check if the TUI is running by
+--- inspecting the client name of each UI:
+---
+--- ```lua
+--- vim.print(vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan).client.name)
+--- ```
+---
 --- @return any[] # Array of UI dictionaries, each with these keys:
 --- - "height"  Requested height of the UI
 --- - "width"   Requested width of the UI
@@ -1661,7 +1673,8 @@ function vim.api.nvim_notify(msg, log_level, opts) end
 --- in a virtual terminal having the intended size.
 ---
 --- Example: this `TermHl` command can be used to display and highlight raw ANSI termcodes, so you
---- can use Nvim as a "scrollback pager" (for terminals like kitty): [terminal-scrollback-pager]()
+--- can use Nvim as a "scrollback pager" (for terminals like kitty): [ansi-colorize]()
+--- [terminal-scrollback-pager]()
 ---
 --- ```lua
 --- vim.api.nvim_create_user_command('TermHl', function()
diff --git a/runtime/lua/vim/health.lua b/runtime/lua/vim/health.lua
index 6dc902489f..ee376f3a11 100644
--- a/runtime/lua/vim/health.lua
+++ b/runtime/lua/vim/health.lua
@@ -11,18 +11,7 @@
 --- <
 --- Plugin authors are encouraged to write new healthchecks. |health-dev|
 ---
----                                                              *g:health*
---- g:health  This global variable controls the behavior and appearance of the
----           `health` floating window. It should be a dictionary containing the
----           following optional keys:
----           - `style`: string? Determines the display style of the `health` window.
----                             Set to `'float'` to enable a floating window. Other
----                             styles are not currently supported.
----
----           Example: >lua
----             vim.g.health = { style = 'float' }
----
---- Commands                                *health-commands*
+--- COMMANDS                                *health-commands*
 ---
 ---                                                              *:che* *:checkhealth*
 --- :che[ckhealth]  Run all healthchecks.
@@ -50,6 +39,23 @@
 ---                         :checkhealth vim*
 --- <
 ---
+--- USAGE                                                        *health-usage*
+---
+--- Local mappings in the healthcheck buffer:
+---
+--- q               Closes the window.
+---
+--- Global configuration:
+---
+---                                                              *g:health*
+--- g:health  Dictionary with the following optional keys:
+---           - `style` (`'float'|nil`) Set to "float" to display :checkhealth in
+---           a floating window instead of the default behavior.
+---
+---           Example: >lua
+---             vim.g.health = { style = 'float' }
+---
+--- --------------------------------------------------------------------------------
 --- Create a healthcheck                                    *health-dev*
 ---
 --- Healthchecks are functions that check the user environment, configuration, or
diff --git a/runtime/lua/vim/lsp/util.lua b/runtime/lua/vim/lsp/util.lua
index 5cccb3321f..ccd68f0fdf 100644
--- a/runtime/lua/vim/lsp/util.lua
+++ b/runtime/lua/vim/lsp/util.lua
@@ -879,8 +879,7 @@ function M.make_floating_popup_options(width, height, opts)
     col = col + (opts.offset_x or 0),
     height = height,
     focusable = opts.focusable,
-    relative = opts.relative == 'mouse' and 'mouse'
-      or opts.relative == 'editor' and 'editor'
+    relative = (opts.relative == 'mouse' or opts.relative == 'editor') and opts.relative
       or 'cursor',
     style = 'minimal',
     width = width,
diff --git a/scripts/vimpatch.lua b/scripts/vimpatch.lua
index cbec50fc17..5d8bea6a98 100755
--- a/scripts/vimpatch.lua
+++ b/scripts/vimpatch.lua
@@ -1,7 +1,7 @@
 --  Updates version.c list of applied Vim patches.
 --
 --  Usage:
---    VIM_SOURCE_DIR=~/neovim/.vim-src/ nvim -V1 -es -i NONE +'luafile ./scripts/vimpatch.lua' +q
+--    VIM_SOURCE_DIR=~/neovim/.vim-src/ nvim -l ./scripts/vimpatch.lua
 
 local nvim = vim.api
 
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index ed9edb1beb..e03a260280 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -766,18 +766,20 @@ void nvim_set_vvar(String name, Object value, Error *err)
   dict_set_var(&vimvardict, name, value, false, false, NULL, err);
 }
 
-/// Echo a message.
+/// Prints a message given by a list of `[text, hl_group]` "chunks".
 ///
-/// @param chunks  A list of `[text, hl_group]` arrays, each representing a
-///                text chunk with specified highlight group name or ID.
-///                `hl_group` element can be omitted for no highlight.
+/// Example:
+/// ```lua
+/// vim.api.nvim_echo({ { 'chunk1-line1\nchunk1-line2\n' }, { 'chunk2-line1' } }, true, {})
+/// ```
+///
+/// @param chunks List of `[text, hl_group]` pairs, where each is a `text` string highlighted by
+///               the (optional) name or ID `hl_group`.
 /// @param history  if true, add to |message-history|.
 /// @param opts  Optional parameters.
-///          - err: Treat the message like |:echoerr|. Omitted `hlgroup`
-///            uses |hl-ErrorMsg| instead.
-///          - verbose: Message is printed as a result of 'verbose' option.
-///            If Nvim was invoked with -V3log_file, the message will be
-///            redirected to the log_file and suppressed from direct output.
+///          - err: Treat the message like `:echoerr`. Sets `hl_group` to |hl-ErrorMsg| by default.
+///          - verbose: Message is controlled by the 'verbose' option. Nvim invoked with `-V3log`
+///            will write the message to the "log" file instead of standard output.
 void nvim_echo(Array chunks, Boolean history, Dict(echo_opts) *opts, Error *err)
   FUNC_API_SINCE(7)
 {
@@ -1000,7 +1002,8 @@ Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err)
 /// in a virtual terminal having the intended size.
 ///
 /// Example: this `TermHl` command can be used to display and highlight raw ANSI termcodes, so you
-/// can use Nvim as a "scrollback pager" (for terminals like kitty): [terminal-scrollback-pager]()
+/// can use Nvim as a "scrollback pager" (for terminals like kitty): [ansi-colorize]()
+/// [terminal-scrollback-pager]()
 ///
 /// ```lua
 /// vim.api.nvim_create_user_command('TermHl', function()
@@ -1500,20 +1503,17 @@ Array nvim_get_api_info(uint64_t channel_id, Arena *arena)
   return rv;
 }
 
-/// Self-identifies the client.
-///
-/// The client/plugin/application should call this after connecting, to provide
-/// hints about its identity and purpose, for debugging and orchestration.
+/// Self-identifies the client. Sets the `client` object returned by |nvim_get_chan_info()|.
 ///
-/// Can be called more than once; the caller should merge old info if
-/// appropriate. Example: library first identifies the channel, then a plugin
-/// using that library later identifies itself.
+/// Clients should call this just after connecting, to provide hints for debugging and
+/// orchestration. (Note: Something is better than nothing! Fields are optional, but at least set
+/// `name`.)
 ///
-/// @note "Something is better than nothing". You don't need to include all the
-///       fields.
+/// Can be called more than once; the caller should merge old info if appropriate. Example: library
+/// first identifies the channel, then a plugin using that library later identifies itself.
 ///
 /// @param channel_id
-/// @param name Short name for the connected client
+/// @param name Client short-name. Sets the `client.name` field of |nvim_get_chan_info()|.
 /// @param version  Dict describing the version, with these
 ///     (optional) keys:
 ///     - "major" major version (defaults to 0 if not set, for no release yet)
@@ -1587,6 +1587,8 @@ void nvim_set_client_info(uint64_t channel_id, String name, Dict version, String
 
 /// Gets information about a channel.
 ///
+/// See |nvim_list_uis()| for an example of how to get channel info.
+///
 /// @param chan channel_id, or 0 for current channel
 /// @returns Channel info dict with these keys:
 ///    - "id"       Channel id.
@@ -1604,8 +1606,8 @@ void nvim_set_client_info(uint64_t channel_id, String name, Dict version, String
 ///                 "/dev/pts/1". If unknown, the key will still be present if a pty is used (e.g.
 ///                 for conpty on Windows).
 ///    -  "buffer"  (optional) Buffer connected to |terminal| instance.
-///    -  "client"  (optional) Info about the peer (client on the other end of the RPC channel),
-///                 which it provided via |nvim_set_client_info()|.
+///    -  "client"  (optional) Info about the peer (client on the other end of the channel), as set
+///                 by |nvim_set_client_info()|.
 ///
 Dict nvim_get_chan_info(uint64_t channel_id, Integer chan, Arena *arena, Error *err)
   FUNC_API_SINCE(4)
@@ -1702,6 +1704,14 @@ Dict nvim__stats(Arena *arena)
 
 /// Gets a list of dictionaries representing attached UIs.
 ///
+/// Example: The Nvim builtin |TUI| sets its channel info as described in |startup-tui|. In
+/// particular, it sets `client.name` to "nvim-tui". So you can check if the TUI is running by
+/// inspecting the client name of each UI:
+///
+/// ```lua
+/// vim.print(vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan).client.name)
+/// ```
+///
 /// @return Array of UI dictionaries, each with these keys:
 ///   - "height"  Requested height of the UI
 ///   - "width"   Requested width of the UI
diff --git a/test/functional/lua/fs_spec.lua b/test/functional/lua/fs_spec.lua
index 218f9bbc46..6bc1ddbff6 100644
--- a/test/functional/lua/fs_spec.lua
+++ b/test/functional/lua/fs_spec.lua
@@ -340,9 +340,6 @@ describe('vim.fs', function()
   end)
 
   describe('normalize()', function()
-    -- local function vim.fs.normalize(path, opts)
-    --   return exec_lua([[return vim.fs.vim.fs.normalize(...)]], path, opts)
-    -- end
     it('removes trailing /', function()
       eq('/home/user', vim.fs.normalize('/home/user/'))
     end)
@@ -389,7 +386,7 @@ describe('vim.fs', function()
       eq('D:foo/test', vim.fs.normalize('d:foo/test/', win_opts))
     end)
 
-    it('does not change case on paths, see #31833', function()
+    it('always treats paths as case-sensitive #31833', function()
       eq('TEST', vim.fs.normalize('TEST', win_opts))
       eq('test', vim.fs.normalize('test', win_opts))
       eq('C:/FOO/test', vim.fs.normalize('C:/FOO/test', win_opts))
diff --git a/test/functional/func/memoize_spec.lua b/test/functional/lua/func_memoize_spec.lua
index ca518ab88d..ca518ab88d 100644
--- a/test/functional/func/memoize_spec.lua
+++ b/test/functional/lua/func_memoize_spec.lua
diff --git a/test/functional/lua/vim_spec.lua b/test/functional/lua/vim_spec.lua
index 9e75861aa0..55e5158596 100644
--- a/test/functional/lua/vim_spec.lua
+++ b/test/functional/lua/vim_spec.lua
@@ -3435,7 +3435,6 @@ stack traceback:
     end)
 
     it('can discard input', function()
-      clear()
       -- discard every other normal 'x' command
       exec_lua [[
         n_key = 0
@@ -3461,7 +3460,6 @@ stack traceback:
     end)
 
     it('callback invalid return', function()
-      clear()
       -- second key produces an error which removes the callback
       exec_lua [[
         n_call = 0