docs: misc #24561

fix #24699
fix #25253

8 files changed, 56 insertions, 46 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index f04fe9bb87..766faee304 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -1505,7 +1505,7 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts})             *nvim_set_keymap()*
       • {rhs}   Right-hand-side |{rhs}| of the mapping.
       • {opts}  Optional parameters map: Accepts all |:map-arguments| as keys
                 except |<buffer>|, values are booleans (default false). Also:
-                • "noremap" non-recursive mapping |:noremap|
+                • "noremap" disables |recursive_mapping|, like |:noremap|
                 • "desc" human-readable description.
                 • "callback" Lua function called in place of {rhs}.
                 • "replace_keycodes" (boolean) When "expr" is true, replace
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 05db977809..2dd290fef1 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -3738,7 +3738,7 @@ jobresize({job}, {width}, {height})                                *jobresize()*
 		Fails if the job was not started with `"pty":v:true`.
 
 jobstart({cmd} [, {opts}])                                          *jobstart()*
-		Note: Prefer |vim.system()| in Lua.
+		Note: Prefer |vim.system()| in Lua (unless using the `pty` option).
 
 		Spawns {cmd} as a job.
 		If {cmd} is a List it runs directly (no 'shell').
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 71c16659eb..f4c581fabe 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -312,6 +312,12 @@ See also |dev-naming|.
 - Avoid functions that depend on cursor position, current buffer, etc. Instead
   the function should take a position parameter, buffer parameter, etc.
 
+Where things go ~
+
+- API (libnvim/RPC): exposes low-level internals, or fundamental things (such
+  as `nvim_exec_lua()`) needed by clients or C consumers.
+- Lua stdlib = high-level functionality that builds on top of the API.
+
 NAMING GUIDELINES                                       *dev-naming*
 
 Naming is exceedingly important: the name of a thing is the primary interface
diff --git a/runtime/doc/intro.txt b/runtime/doc/intro.txt
index 975aff6bf6..299c18ac2e 100644
--- a/runtime/doc/intro.txt
+++ b/runtime/doc/intro.txt
@@ -536,7 +536,7 @@ CTRL-O in Insert mode you get a beep but you are still in Insert mode, type
  Visual		 *2		  ^G	 c C	    --	      :       --
  Select		 *5	^O ^G		 *6	    --	      --      --
  Insert		 <Esc>	  --	  --		  <Insert>    --      --
- Replace		 <Esc>	  --	  --	<Insert>	      --      --
+ Replace	 <Esc>	  --	  --	<Insert>	      --      --
  Command-line	 `*3`	  --	  --	 :start	    --		      --
  Ex		 :vi	  --	  --	 --	    --	      --
 
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 6cfec45523..efba10b86f 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1880,25 +1880,22 @@ vim.deepcopy({orig})                                          *vim.deepcopy()*
     Return: ~
         (table) Table of copied keys and (nested) values.
 
-vim.defaulttable({create})                                *vim.defaulttable()*
-    Creates a table whose members are automatically created when accessed, if
-    they don't already exist.
+vim.defaulttable({createfn})                              *vim.defaulttable()*
+    Creates a table whose missing keys are provided by {createfn} (like
+    Python's "defaultdict").
 
-    They mimic defaultdict in python.
-
-    If {create} is `nil`, this will create a defaulttable whose constructor
-    function is this function, effectively allowing to create nested tables on
-    the fly: >lua
+    If {createfn} is `nil` it defaults to defaulttable() itself, so accessing
+    nested keys creates nested tables: >lua
         local a = vim.defaulttable()
         a.b.c = 1
 <
 
     Parameters: ~
-      • {create}  function?(key:any):any The function called to create a
-                  missing value.
+      • {createfn}  function?(key:any):any Provides the value for a missing
+                    `key`.
 
     Return: ~
-        (table) Empty table with metamethod
+        (table) Empty table with `__index` metamethod.
 
 vim.endswith({s}, {suffix})                                   *vim.endswith()*
     Tests if `s` ends with `suffix`.
@@ -2061,13 +2058,13 @@ vim.Ringbuf:push({item})                                      *Ringbuf:push()*
       • {item}  any
 
 vim.spairs({t})                                                 *vim.spairs()*
-    Enumerate a table sorted by its keys.
+    Enumerates key-value pairs of a table, ordered by key.
 
     Parameters: ~
       • {t}  (table) Dict-like table
 
     Return: ~
-        (function) iterator over sorted keys and their values
+        (function) |for-in| iterator over sorted keys and their values
 
     See also: ~
       • Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua
@@ -2232,12 +2229,14 @@ vim.tbl_get({o}, {...})                                        *vim.tbl_get()*
         any Nested value indexed by key (if it exists), else nil
 
 vim.tbl_isarray({t})                                       *vim.tbl_isarray()*
-    Tests if a Lua table can be treated as an array (a table indexed by
-    integers).
+    Tests if `t` is an "array": a table indexed only by integers (potentially non-contiguous).
+
+    If the indexes start from 1 and are contiguous then the array is also a
+    list. |vim.tbl_islist()|
 
-    Empty table `{}` is assumed to be an array, unless it was created by
-    |vim.empty_dict()| or returned as a dict-like |API| or Vimscript result,
-    for example from |rpcrequest()| or |vim.fn|.
+    Empty table `{}` is an array, unless it was created by |vim.empty_dict()|
+    or returned as a dict-like |API| or Vimscript result, for example from
+    |rpcrequest()| or |vim.fn|.
 
     Parameters: ~
       • {t}  (table)
@@ -2245,6 +2244,9 @@ vim.tbl_isarray({t})                                       *vim.tbl_isarray()*
     Return: ~
         (boolean) `true` if array-like table, else `false`.
 
+    See also: ~
+      • https://github.com/openresty/luajit2#tableisarray
+
 vim.tbl_isempty({t})                                       *vim.tbl_isempty()*
     Checks if a table is empty.
 
@@ -2258,12 +2260,12 @@ vim.tbl_isempty({t})                                       *vim.tbl_isempty()*
       • https://github.com/premake/premake-core/blob/master/src/base/table.lua
 
 vim.tbl_islist({t})                                         *vim.tbl_islist()*
-    Tests if a Lua table can be treated as a list (a table indexed by
-    consecutive integers starting from 1).
+    Tests if `t` is a "list": a table indexed only by contiguous integers starting from 1 (what |lua-length| calls a "regular
+    array").
 
-    Empty table `{}` is assumed to be an list, unless it was created by
-    |vim.empty_dict()| or returned as a dict-like |API| or Vimscript result,
-    for example from |rpcrequest()| or |vim.fn|.
+    Empty table `{}` is a list, unless it was created by |vim.empty_dict()| or
+    returned as a dict-like |API| or Vimscript result, for example from
+    |rpcrequest()| or |vim.fn|.
 
     Parameters: ~
       • {t}  (table)
@@ -2271,6 +2273,9 @@ vim.tbl_islist({t})                                         *vim.tbl_islist()*
     Return: ~
         (boolean) `true` if list-like table, else `false`.
 
+    See also: ~
+      • |vim.tbl_isarray()|
+
 vim.tbl_keys({t})                                             *vim.tbl_keys()*
     Return a list of all keys used in a table. However, the order of the
     return table of keys is not guaranteed.
diff --git a/runtime/doc/luaref.txt b/runtime/doc/luaref.txt
index 341f620a8d..467b5760cf 100644
--- a/runtime/doc/luaref.txt
+++ b/runtime/doc/luaref.txt
@@ -568,8 +568,7 @@ Binary operators comprise arithmetic operators (see |lua-arithmetic|),
 relational operators (see |lua-relational|), logical operators (see
 |lua-logicalop|), and the concatenation operator (see |lua-concat|).
 Unary operators comprise the unary minus (see |lua-arithmetic|), the unary
-`not` (see |lua-logicalop|), and the unary length operator (see
-|lua-length|).
+`not` (see |lua-logicalop|), and the unary length operator (see |lua-length|).
 
 Both function calls and vararg expressions may result in multiple values. If
 the expression is used as a statement (see |lua-funcstatement|)
@@ -690,7 +689,7 @@ according to the rules mentioned in |lua-coercion|. Otherwise, the
 "concat" metamethod is called (see |lua-metatable|).
 
 ------------------------------------------------------------------------------
-2.5.5  The Length Operator                                   *lua-length*
+2.5.5  The Length Operator                                   *lua-#* *lua-length*
 
 The length operator is denoted by the unary operator `#`. The length of a
 string is its number of bytes (that is, the usual meaning of string length
@@ -3505,7 +3504,7 @@ luaL_where                                                        *luaL_where()*
         This function is used to build a prefix for error messages.
 
 ==============================================================================
-5  STANDARD LIBRARIES                                               *lua-Lib*
+5  STANDARD LIBRARIES                                               *lua-lib*
 
 The standard libraries provide useful functions that are implemented directly
 through the C API. Some of these functions provide essential services to the
@@ -3653,8 +3652,8 @@ next({table} [, {index}])                               *next()*
         argument is absent, then it is interpreted as `nil`. In particular,
         you can use `next(t)` to check whether a table is empty.
 
-        The order in which the indices are enumerated is not specified, `even
-        for` `numeric indices`. (To traverse a table in numeric order, use a
+        The order in which the indices are enumerated is not specified, even
+        for numeric indices. (To traverse a table in numeric order, use a
         numerical `for` or the |ipairs()| function.)
 
         The behavior of `next` is `undefined` if, during the traversal, you
@@ -3759,7 +3758,7 @@ unpack({list} [, {i} [, {j}]])                          *unpack()*
 <
         except that the above code can be written only for a fixed number of
         elements. By default, {i} is 1 and {j} is the length of the list, as
-        defined by the length operator(see |lua-length|).
+        defined by the length operator (see |lua-length|).
 
 _VERSION                                                *_VERSION*
         A global variable (not a function) that holds a string containing the
@@ -4299,12 +4298,11 @@ table.remove({table} [, {pos}])                                 *table.remove()*
 
 table.sort({table} [, {comp}])                                    *table.sort()*
         Sorts table elements in a given order, `in-place`, from `table[1]` to
-        `table[n]`, where `n` is the length of the table (see
-        |lua-length|). If {comp} is given, then it must be a function
-        that receives two table elements, and returns true when the first is
-        less than the second (so that `not comp(a[i+1],a[i])` will be true
-        after the sort). If {comp} is not given, then the standard Lua
-        operator `<` is used instead.
+        `table[n]`, where `n` is the length of the table (see |lua-length|).
+        If {comp} is given, then it must be a function that receives two table
+        elements, and returns true when the first is less than the second (so
+        that `not comp(a[i+1],a[i])` will be true after the sort). If {comp}
+        is not given, then the standard Lua operator `<` is used instead.
 
 The sort algorithm is `not` stable, that is, elements considered equal by the
 given order may have their relative positions changed by the sort.
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index e1518c58bb..96bf2eef63 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -3235,9 +3235,8 @@ A jump table for the options with a short description can be found at |Q_op|.
 			*'ignorecase'* *'ic'* *'noignorecase'* *'noic'*
 'ignorecase' 'ic'	boolean	(default off)
 			global
-	Ignore case in search patterns.  Also used when searching in the tags
-	file.
-	Also see 'smartcase' and 'tagcase'.
+	Ignore case in search patterns, completion, and when searching the tags file.
+	See also 'smartcase' and 'tagcase'.
 	Can be overruled by using "\c" or "\C" in the pattern, see
 	|/ignorecase|.
 
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 10f689bad7..34971c7acf 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -854,12 +854,14 @@ add_predicate({name}, {handler}, {force})
       • {force}    (boolean|nil)
 
 edit({lang})                                     *vim.treesitter.query.edit()*
-    Open a window for live editing of a treesitter query.
+    Opens a live editor to query the buffer you started from.
 
-    Can also be shown with `:EditQuery`.                          *:EditQuery*
+    Can also be shown with *:EditQuery*.
 
-    Note that the editor opens a scratch buffer, and so queries aren't
-    persisted on disk.
+    If you move the cursor to a capture name ("@foo"), text matching the
+    capture is highlighted in the source buffer. The query editor is a scratch
+    buffer, use `:write` to save it. You can find example queries at
+    `$VIMRUNTIME/queries/`.
 
     Parameters: ~
       • {lang}  (string|nil) language to open the query editor for. If