docs: misc #31479

15 files changed, 154 insertions, 116 deletions

diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt
index dc9b0735ea..c2d220041c 100644
--- a/runtime/doc/channel.txt
+++ b/runtime/doc/channel.txt
@@ -11,21 +11,20 @@ Nvim asynchronous IO					*channel*
 ==============================================================================
 1. Introduction						    *channel-intro*
 
-Channels are nvim's way of communicating with external processes.
+Channels are Nvim's way of communicating with external processes.
 
 There are several ways to open a channel:
 
-  1. Through stdin/stdout when `nvim` is started with `--headless`, and a startup
-     script or --cmd  command opens the stdio channel using |stdioopen()|.
+  1. Through stdin/stdout when `nvim` is started with `--headless` and a startup
+     script or `--cmd` command opens the stdio channel using |stdioopen()|.
 
   2. Through stdin, stdout and stderr of a process spawned by |jobstart()|.
 
-  3. Through the PTY master end of a PTY opened with |nvim_open_term()| or
-     `jobstart(…, {'pty': v:true})`.
+  3. Through the PTY master end opened with `jobstart(…, {'pty': v:true})`.
 
   4. By connecting to a TCP/IP socket or named pipe with |sockconnect()|.
 
-  5. By another process connecting to a socket listened to by nvim. This only
+  5. By another process connecting to a socket listened to by Nvim. This only
      supports RPC channels, see |rpc-connecting|.
 
 Channels support multiple modes or protocols. In the most basic
@@ -146,7 +145,7 @@ from the host TTY, or if Nvim is |--headless| it uses default values: >vim
     :echo system('nvim --headless +"te stty -a" +"sleep 1" +"1,/^$/print" +q')
 
 ==============================================================================
-3. Communicating using msgpack-rpc			      *channel-rpc*
+3. Communicating with msgpack RPC			      *channel-rpc*
 
 When channels are opened with the `rpc` option set to true, the channel can be
 used for remote method calls in both directions, see |msgpack-rpc|. Note that
diff --git a/runtime/doc/gui.txt b/runtime/doc/gui.txt
index 380fa71537..eb787af3c9 100644
--- a/runtime/doc/gui.txt
+++ b/runtime/doc/gui.txt
@@ -17,10 +17,14 @@ TUI and GUI (assuming the UI supports the given feature). See |TUI| for notes
 specific to the terminal UI. Help tags with the "gui-" prefix refer to UI
 features, whereas help tags with the "ui-" prefix refer to the |ui-protocol|.
 
-Nvim provides a default, builtin UI (the |TUI|), but there are many other
-(third-party) GUIs that you can use instead:
+==============================================================================
+Third-party GUIs                                *third-party-guis* *vscode*
+
+Nvim provides a builtin "terminal UI" (|TUI|), but also works with many
+(third-party) GUIs which may provide a fresh look or extra features on top of
+Nvim. For example, "vscode-neovim" essentally allows you to use VSCode as
+a Nvim GUI.
 
-                                                        *vscode*
 - vscode-neovim (Nvim in VSCode!) https://github.com/vscode-neovim/vscode-neovim
 - Firenvim (Nvim in your web browser!) https://github.com/glacambre/firenvim
 - Neovide https://neovide.dev/
diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt
index ac019a4f25..0c654b8b30 100644
--- a/runtime/doc/intro.txt
+++ b/runtime/doc/intro.txt
@@ -32,8 +32,9 @@ and |user-manual|.
 Resources                                               *resources*
 
                                                 *internet* *www* *distribution*
-- Nvim home page: https://neovim.io/
-- Vim FAQ: https://vimhelp.org/vim_faq.txt.html
+Nvim home page:
+
+        https://neovim.io/
 
                                                 *book*
 There are many resources to learn Vi, Vim, and Nvim.  We recommend:
@@ -48,6 +49,7 @@ There are many resources to learn Vi, Vim, and Nvim.  We recommend:
 - For more information try one of these:
   - https://iccf-holland.org/click5.html
   - https://www.vim.org/iccf/click5.html
+- Vim FAQ: https://vimhelp.org/vim_faq.txt.html
 
                                                 *bugs* *bug-report* *feature-request*
 Report bugs and request features here: https://github.com/neovim/neovim/issues
@@ -67,18 +69,24 @@ To install or upgrade Nvim, you can...
 - Build from source:
   https://github.com/neovim/neovim/blob/master/INSTALL.md#install-from-source
 
-                                                *uninstall*
+------------------------------------------------------------------------------
+Un-installing Nvim                                      *uninstall*
+
 To uninstall Nvim:
-- If you downloaded a pre-built archive or built Nvim from source (e.g. `make
-  install`), just delete its files, typically located in: >
+- If you downloaded a pre-built archive or built Nvim from source (e.g.
+  `make install`), just delete its files, typically located in: >
   /usr/local/bin/nvim
   /usr/local/share/nvim
 <
+  - To find where Nvim is installed, run these commands: >
+    :echo v:progpath
+    :echo $VIMRUNTIME
+<
 - If you installed via package manager, read your package manager's
   documentation. Common examples:
   - APT (Debian, Ubuntu, …): `apt-get remove neovim`
-  - Homebrew (macOS): `brew install neovim`
-  - Scoop (Windows): `scoop install neovim`
+  - Homebrew (macOS): `brew uninstall neovim`
+  - Scoop (Windows): `scoop uninstall neovim`
 
 ==============================================================================
 Sponsor Vim/Nvim development                            *sponsor* *register*
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 16f543088b..71e8a12ca3 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -344,22 +344,17 @@ Each response handler has this signature: >
                                                       *lsp-handler-resolution*
 Handlers can be set by (in increasing priority):
 
-- Setting a field in vim.lsp.handlers.                      *vim.lsp.handlers*
-  `vim.lsp.handlers` is a global table that contains the default mapping of
-  |lsp-method| names to lsp-handlers.
-
+                                                            *vim.lsp.handlers*
+- Setting a field in `vim.lsp.handlers`. This global table contains the
+  default mappings of |lsp-method| names to handlers. (Note: only for
+  server-to-client requests/notifications, not client-to-server.)
   Example: >lua
-
     vim.lsp.handlers['textDocument/publishDiagnostics'] = my_custom_diagnostics_handler
 <
-  Note: this only applies for requests/notifications made by the
-  server to the client.
-
-- The {handlers} parameter of |vim.lsp.start()|. This sets the default
-  |lsp-handler| for a specific server.
-
+- Passing a {handlers} parameter to |vim.lsp.start()|. This sets the default
+  |lsp-handler| for a specific server. (Note: only for server-to-client
+  requests/notifications, not client-to-server.)
   Example: >lua
-
     vim.lsp.start {
       ..., -- Other configuration omitted.
       handlers = {
@@ -367,14 +362,9 @@ Handlers can be set by (in increasing priority):
       },
     }
 <
-  Note: this only applies for requests/notifications made by the
-  server to the client.
-
-- The {handler} parameter of |vim.lsp.buf_request_all()|. This sets
-  the |lsp-handler| ONLY for the given request(s).
-
+- Passing a {handler} parameter to |vim.lsp.buf_request_all()|. This sets the
+  |lsp-handler| ONLY for the given request(s).
   Example: >lua
-
     vim.lsp.buf_request_all(
       0,
       'textDocument/publishDiagnostics',
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 022adb3da7..25e58c0240 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -817,8 +817,8 @@ vim.json.encode({obj}, {opts})                             *vim.json.encode()*
     Parameters: ~
       • {obj}   (`any`)
       • {opts}  (`table<string,any>?`) Options table with keys:
-                • escape_slash: (boolean) (default false) When true, escapes
-                  `/` character in JSON strings
+                • escape_slash: (boolean) (default false) Escape slash
+                  characters "/" in string values.
 
     Return: ~
         (`string`)
@@ -3062,11 +3062,13 @@ vim.fs.find({names}, {opts})                                   *vim.fs.find()*
         items
 
 vim.fs.joinpath({...})                                     *vim.fs.joinpath()*
-    Concatenates partial paths into one path. Slashes are normalized
-    (redundant slashes are removed, and on Windows backslashes are replaced
-    with forward-slashes) (e.g., `"foo/"` and `"/bar"` get joined to
-    `"foo/bar"`) (windows: e.g `"a\foo\"` and `"\bar"` are joined to
-    `"a/foo/bar"`)
+    Concatenates partial paths (one absolute or relative path followed by zero
+    or more relative paths). Slashes are normalized: redundant slashes are
+    removed, and (on Windows) backslashes are replaced with forward-slashes.
+
+    Examples:
+    • "foo/", "/bar" => "foo/bar"
+    • Windows: "a\foo\", "\bar" => "a/foo/bar"
 
     Attributes: ~
         Since: 0.10.0
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index 34cf309576..1e472422ce 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -12,7 +12,7 @@ manual.
                                       Type |gO| to see the table of contents.
 
 ==============================================================================
-1. Key mapping			      *keybind* *key-mapping* *mapping* *macro*
+1. Key mapping				*keybind* *key-mapping* *mapping*
 
 Key mapping is used to change the meaning of typed keys.  The most common use
 is to define a sequence of commands for a function key.  Example: >
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 49d9bb5ce0..9ab0a01b99 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -67,7 +67,6 @@ DEFAULTS
   current buffer, respectively.
 • 'number', 'relativenumber', 'signcolumn', and 'foldcolumn' are disabled in
   |terminal| buffers. See |terminal-config| for an example of changing these defaults.
-• |vim.json.encode()| no longer escapes the forward slash symbol by default
 
 DIAGNOSTICS
 
@@ -137,6 +136,7 @@ LUA
 • Command-line completions for: `vim.g`, `vim.t`, `vim.w`, `vim.b`, `vim.v`,
   `vim.o`, `vim.wo`, `vim.bo`, `vim.opt`, `vim.opt_local`, `vim.opt_global`,
   and `vim.fn`.
+• |vim.json.encode()| no longer escapes forward slashes "/" by default
 
 OPTIONS
 
@@ -192,7 +192,6 @@ The following new features were added.
 API
 
 • |nvim__ns_set()| can set properties for a namespace
-• |vim.json.encode()| has an option to enable forward slash escaping
 
 DEFAULTS
 
@@ -270,6 +269,7 @@ LUA
   is more performant and easier to read.
 • |vim.str_byteindex()| and |vim.str_utfindex()| gained overload signatures
   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.
 
 OPTIONS
@@ -282,6 +282,8 @@ PERFORMANCE
 
 • Significantly reduced redraw time for long lines with treesitter
   highlighting.
+• LSP diagnostics and inlay hints are de-duplicated (new requests cancel
+  inflight requests). This greatly improves performance with slow LSP servers.
 
 PLUGINS
 
diff --git a/runtime/doc/repeat.txt b/runtime/doc/repeat.txt
index abeefb980e..e65caa72ed 100644
--- a/runtime/doc/repeat.txt
+++ b/runtime/doc/repeat.txt
@@ -111,7 +111,7 @@ To abort this type CTRL-C twice.
 ==============================================================================
 Complex repeats						*complex-repeat*
 
-							*q* *recording*
+							*q* *recording* *macro*
 q{0-9a-zA-Z"}		Record typed characters into register {0-9a-zA-Z"}
 			(uppercase to append).  The 'q' command is disabled
 			while executing a register, and it doesn't work inside
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index a0860c60a6..956fb80e73 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -81,8 +81,7 @@ that user config takes precedence over plugins, which take precedence over
 queries bundled with Nvim). If a query should extend other queries instead
 of replacing them, use |treesitter-query-modeline-extends|.
 
-See |lua-treesitter-query| for the list of available methods for working with
-treesitter queries from Lua.
+The Lua interface is described at |lua-treesitter-query|.
 
 
 TREESITTER QUERY PREDICATES                            *treesitter-predicates*
@@ -1195,6 +1194,10 @@ register({lang}, {filetype})              *vim.treesitter.language.register()*
 ==============================================================================
 Lua module: vim.treesitter.query                        *lua-treesitter-query*
 
+This Lua |treesitter-query| interface allows you to create queries and use
+them to parse text. See |vim.treesitter.query.parse()| for a working example.
+
+
                                         *vim.treesitter.query.add_directive()*
 add_directive({name}, {handler}, {opts})
     Adds a new directive to be used in queries
@@ -1325,21 +1328,30 @@ omnifunc({findstart}, {base})                *vim.treesitter.query.omnifunc()*
       • {base}       (`string`)
 
 parse({lang}, {query})                          *vim.treesitter.query.parse()*
-    Parse {query} as a string. (If the query is in a file, the caller should
-    read the contents into a string before calling).
-
-    Returns a `Query` (see |lua-treesitter-query|) object which can be used to
-    search nodes in the syntax tree for the patterns defined in {query} using
-    the `iter_captures` and `iter_matches` methods.
-
-    Exposes `info` and `captures` with additional context about {query}.
-    • `captures` contains the list of unique capture names defined in {query}.
-    • `info.captures` also points to `captures`.
-    • `info.patterns` contains information about predicates.
+    Parses a {query} string and returns a `Query` object
+    (|lua-treesitter-query|), which can be used to search the tree for the
+    query patterns (via |Query:iter_captures()|, |Query:iter_matches()|), or
+    inspect the query via these fields:
+    • `captures`: a list of unique capture names defined in the query (alias:
+      `info.captures`).
+    • `info.patterns`: information about predicates.
+
+    Example (select the code then run `:'<,'>lua` to try it): >lua
+        local query = vim.treesitter.query.parse('vimdoc', [[
+          ; query
+          ((h1) @str
+            (#trim! @str 1 1 1 1))
+        ]])
+        local tree = vim.treesitter.get_parser():parse()[1]
+        for id, node, metadata in query:iter_captures(tree:root(), 0) do
+           -- Print the node name and source text.
+           vim.print({node:type(), vim.treesitter.get_node_text(node, vim.api.nvim_get_current_buf())})
+        end
+<
 
     Parameters: ~
       • {lang}   (`string`) Language to use for the query
-      • {query}  (`string`) Query in s-expr syntax
+      • {query}  (`string`) Query text, in s-expr syntax
 
     Return: ~
         (`vim.treesitter.Query`) Parsed query
@@ -1349,18 +1361,23 @@ parse({lang}, {query})                          *vim.treesitter.query.parse()*
 
                                                        *Query:iter_captures()*
 Query:iter_captures({node}, {source}, {start}, {stop})
-    Iterate over all captures from all matches inside {node}
-
-    {source} is needed if the query contains predicates; then the caller must
-    ensure to use a freshly parsed tree consistent with the current text of
-    the buffer (if relevant). {start} and {stop} can be used to limit matches
-    inside a row range (this is typically used with root node as the {node},
-    i.e., to get syntax highlight matches in the current viewport). When
-    omitted, the {start} and {stop} row values are used from the given node.
-
-    The iterator returns four values: a numeric id identifying the capture,
-    the captured node, metadata from any directives processing the match, and
-    the match itself. The following example shows how to get captures by name: >lua
+    Iterates over all captures from all matches in {node}.
+
+    {source} is required if the query contains predicates; then the caller
+    must ensure to use a freshly parsed tree consistent with the current text
+    of the buffer (if relevant). {start} and {stop} can be used to limit
+    matches inside a row range (this is typically used with root node as the
+    {node}, i.e., to get syntax highlight matches in the current viewport).
+    When omitted, the {start} and {stop} row values are used from the given
+    node.
+
+    The iterator returns four values:
+    1. the numeric id identifying the capture
+    2. the captured node
+    3. metadata from any directives processing the match
+    4. the match itself
+
+    Example: how to get captures by name: >lua
         for id, node, metadata, match in query:iter_captures(tree:root(), bufnr, first, last) do
           local name = query.captures[id] -- name of the capture in the query
           -- typically useful info about the node:
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index c93d2b119e..9f28b373ee 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -24,7 +24,7 @@ User configuration and data files are found in standard |base-directories|
   session information.  |shada|
 
 ==============================================================================
-Defaults                                                    *nvim-defaults*
+Defaults                                            *defaults* *nvim-defaults*
 
 - Filetype detection is enabled by default. This can be disabled by adding
   ":filetype off" to |init.vim|.
@@ -291,7 +291,8 @@ Commands:
   User commands can support |:command-preview| to show results as you type
 - |:write| with "++p" flag creates parent directories.
 
-Events:
+Events (autocommands):
+- Fixed inconsistent behavior in execution of nested autocommands #23368
 - |RecordingEnter|
 - |RecordingLeave|
 - |SearchWrapped|
@@ -299,6 +300,8 @@ Events:
 - |TabNewEntered|
 - |TermClose|
 - |TermOpen|
+- |TermResponse| is fired for any OSC sequence received from the terminal,
+  instead of the Primary Device Attributes response. |v:termresponse|
 - |UIEnter|
 - |UILeave|
 
@@ -366,7 +369,7 @@ Options:
 - 'shortmess'
     - "F" flag does not affect output from autocommands.
     - "q" flag fully hides macro recording message.
-- 'signcolumn'  supports up to 9 dynamic/fixed columns
+- 'signcolumn'  can show multiple signs (dynamic or fixed columns)
 - 'statuscolumn' full control of columns using 'statusline' format
 - 'tabline'     middle-click on tabpage label closes tabpage,
                 and %@Func@foo%X can call any function on mouse-click
@@ -375,6 +378,10 @@ Options:
 - 'winblend'    pseudo-transparency in floating windows |api-floatwin|
 - 'winhighlight' window-local highlights
 
+Performance:
+- Signs are implemented using Nvim's internal "marktree" (btree) structure.
+- Folds are not updated during insert-mode.
+
 Providers:
 - If a Python interpreter is available on your `$PATH`, |:python| and
   |:python3| are always available. See |provider-python|.
@@ -392,6 +399,7 @@ Shell:
 - |system()| does not support writing/reading "backgrounded" commands. |E5677|
 
 Signs:
+- 'signcolumn' can show multiple signs.
 - Signs are removed if the associated line is deleted.
 - Signs placed twice with the same identifier in the same group are moved.
 
@@ -584,9 +592,6 @@ Mappings:
 Motion:
 - The |jumplist| avoids useless/phantom jumps.
 
-Performance:
-- Folds are not updated during insert-mode.
-
 Syntax highlighting:
 - syncolor.vim has been removed. Nvim now sets up default highlighting groups
   automatically for both light and dark backgrounds, regardless of whether or
@@ -611,12 +616,6 @@ Working directory (Vim implemented some of these after Nvim):
 - `getcwd(-1)` is equivalent to `getcwd(-1, 0)` instead of returning the global
   working directory. Use `getcwd(-1, -1)` to get the global working directory.
 
-Autocommands:
-- Fixed inconsistent behavior in execution of nested autocommands:
-  https://github.com/neovim/neovim/issues/23368
-- |TermResponse| is fired for any OSC sequence received from the terminal,
-  instead of the Primary Device Attributes response. |v:termresponse|
-
 Options:
 - 'titlestring' uses printf-style '%' items (see: 'statusline') to implement
   the default behaviour. The implementation is equivalent to setting
diff --git a/runtime/lua/vim/_meta/json.lua b/runtime/lua/vim/_meta/json.lua
index 1a7e87db9c..0d59de5fa6 100644
--- a/runtime/lua/vim/_meta/json.lua
+++ b/runtime/lua/vim/_meta/json.lua
@@ -25,18 +25,18 @@ vim.json = {}
 ---
 ---@param str string Stringified JSON data.
 ---@param opts? table<string,any> Options table with keys:
----                                 - luanil: (table) Table with keys:
----                                   * object: (boolean) When true, converts `null` in JSON objects
----                                                       to Lua `nil` instead of |vim.NIL|.
----                                   * array: (boolean) When true, converts `null` in JSON arrays
----                                                      to Lua `nil` instead of |vim.NIL|.
+---                               - luanil: (table) Table with keys:
+---                                 - object: (boolean) When true, converts `null` in JSON objects
+---                                   to Lua `nil` instead of |vim.NIL|.
+---                                 - array: (boolean) When true, converts `null` in JSON arrays
+---                                   to Lua `nil` instead of |vim.NIL|.
 ---@return any
 function vim.json.decode(str, opts) end
 
 --- Encodes (or "packs") Lua object {obj} as JSON in a Lua string.
 ---@param obj any
 ---@param opts? table<string,any> Options table with keys:
----                                 - escape_slash: (boolean) (default false) When true, escapes `/`
----                                                           character in JSON strings
+---                                 - escape_slash: (boolean) (default false) Escape slash
+---                                   characters "/" in string values.
 ---@return string
 function vim.json.encode(obj, opts) end
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index 1b774d5cab..d042df96e5 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -105,9 +105,13 @@ function M.basename(file)
   return file:match('/$') and '' or (file:match('[^/]*$'))
 end
 
---- Concatenates partial paths into one path. Slashes are normalized (redundant slashes are removed, and on Windows backslashes are replaced with forward-slashes)
---- (e.g., `"foo/"` and `"/bar"` get joined to `"foo/bar"`)
---- (windows: e.g `"a\foo\"` and `"\bar"` are joined to `"a/foo/bar"`)
+--- Concatenates partial paths (one absolute or relative path followed by zero or more relative
+--- paths). Slashes are normalized: redundant slashes are removed, and (on Windows) backslashes are
+--- replaced with forward-slashes.
+---
+--- Examples:
+--- - "foo/", "/bar" => "foo/bar"
+--- - Windows: "a\foo\", "\bar" => "a/foo/bar"
 ---
 ---@since 12
 ---@param ... string
diff --git a/runtime/lua/vim/treesitter/query.lua b/runtime/lua/vim/treesitter/query.lua
index dbe3d54c2f..f9c497337f 100644
--- a/runtime/lua/vim/treesitter/query.lua
+++ b/runtime/lua/vim/treesitter/query.lua
@@ -1,3 +1,6 @@
+--- @brief This Lua |treesitter-query| interface allows you to create queries and use them to parse
+--- text. See |vim.treesitter.query.parse()| for a working example.
+
 local api = vim.api
 local language = require('vim.treesitter.language')
 local memoize = vim.func._memoize
@@ -8,9 +11,9 @@ local M = {}
 ---Parsed query, see |vim.treesitter.query.parse()|
 ---
 ---@class vim.treesitter.Query
----@field lang string name of the language for this parser
+---@field lang string parser language name
 ---@field captures string[] list of (unique) capture names defined in query
----@field info vim.treesitter.QueryInfo contains information used in the query (e.g. captures, predicates, directives)
+---@field info vim.treesitter.QueryInfo query context (e.g. captures, predicates, directives)
 ---@field query TSQuery userdata query object
 local Query = {}
 Query.__index = Query
@@ -228,20 +231,28 @@ M.get = memoize('concat-2', function(lang, query_name)
   return M.parse(lang, query_string)
 end)
 
---- Parse {query} as a string. (If the query is in a file, the caller
---- should read the contents into a string before calling).
----
---- Returns a `Query` (see |lua-treesitter-query|) object which can be used to
---- search nodes in the syntax tree for the patterns defined in {query}
---- using the `iter_captures` and `iter_matches` methods.
+--- Parses a {query} string and returns a `Query` object (|lua-treesitter-query|), which can be used
+--- to search the tree for the query patterns (via |Query:iter_captures()|, |Query:iter_matches()|),
+--- or inspect the query via these fields:
+---   - `captures`: a list of unique capture names defined in the query (alias: `info.captures`).
+---   - `info.patterns`: information about predicates.
 ---
---- Exposes `info` and `captures` with additional context about {query}.
----   - `captures` contains the list of unique capture names defined in {query}.
----   - `info.captures` also points to `captures`.
----   - `info.patterns` contains information about predicates.
+--- Example (select the code then run `:'<,'>lua` to try it):
+--- ```lua
+--- local query = vim.treesitter.query.parse('vimdoc', [[
+---   ; query
+---   ((h1) @str
+---     (#trim! @str 1 1 1 1))
+--- ]])
+--- local tree = vim.treesitter.get_parser():parse()[1]
+--- for id, node, metadata in query:iter_captures(tree:root(), 0) do
+---    -- Print the node name and source text.
+---    vim.print({node:type(), vim.treesitter.get_node_text(node, vim.api.nvim_get_current_buf())})
+--- end
+--- ```
 ---
 ---@param lang string Language to use for the query
----@param query string Query in s-expr syntax
+---@param query string Query text, in s-expr syntax
 ---
 ---@return vim.treesitter.Query : Parsed query
 ---
@@ -847,20 +858,22 @@ local function match_id_hash(_, match)
   return (match:info())
 end
 
---- Iterate over all captures from all matches inside {node}
+--- Iterates over all captures from all matches in {node}.
 ---
---- {source} is needed if the query contains predicates; then the caller
+--- {source} is required if the query contains predicates; then the caller
 --- must ensure to use a freshly parsed tree consistent with the current
 --- text of the buffer (if relevant). {start} and {stop} can be used to limit
 --- matches inside a row range (this is typically used with root node
 --- as the {node}, i.e., to get syntax highlight matches in the current
 --- viewport). When omitted, the {start} and {stop} row values are used from the given node.
 ---
---- The iterator returns four values: a numeric id identifying the capture,
---- the captured node, metadata from any directives processing the match,
---- and the match itself.
---- The following example shows how to get captures by name:
+--- The iterator returns four values:
+--- 1. the numeric id identifying the capture
+--- 2. the captured node
+--- 3. metadata from any directives processing the match
+--- 4. the match itself
 ---
+--- Example: how to get captures by name:
 --- ```lua
 --- for id, node, metadata, match in query:iter_captures(tree:root(), bufnr, first, last) do
 ---   local name = query.captures[id] -- name of the capture in the query
diff --git a/test/functional/lua/fs_spec.lua b/test/functional/lua/fs_spec.lua
index 3c306e6824..140fe66961 100644
--- a/test/functional/lua/fs_spec.lua
+++ b/test/functional/lua/fs_spec.lua
@@ -469,7 +469,7 @@ describe('vim.fs', function()
     end)
   end)
 
-  describe('abspath', function()
+  describe('abspath()', function()
     local cwd = is_os('win') and vim.uv.cwd():gsub('\\', '/') or vim.uv.cwd()
     local home = is_os('win') and vim.uv.os_homedir():gsub('\\', '/') or vim.uv.os_homedir()
 
diff --git a/test/functional/lua/json_spec.lua b/test/functional/lua/json_spec.lua
index 8df42fcaa1..e4a1df1d4c 100644
--- a/test/functional/lua/json_spec.lua
+++ b/test/functional/lua/json_spec.lua
@@ -152,7 +152,7 @@ describe('vim.json.encode()', function()
     clear()
   end)
 
-  it('dumps strings with & without escaped slash', function()
+  it('escape_slash', function()
     -- With slash
     eq('"Test\\/"', exec_lua([[return vim.json.encode('Test/', { escape_slash = true })]]))
     eq(