Merge #24351 docs

10 files changed, 91 insertions, 80 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 417137c166..793fcd703b 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -1849,6 +1849,9 @@ nvim_get_commands({*opts})                               *nvim_get_commands()*
     Return: ~
         Map of maps describing commands.
 
+    See also: ~
+      • |nvim_get_all_options_info()|
+
 nvim_parse_cmd({str}, {opts})                               *nvim_parse_cmd()*
     Parse command line.
 
@@ -1933,6 +1936,9 @@ nvim_get_all_options_info()                      *nvim_get_all_options_info()*
     Return: ~
         dictionary of all options
 
+    See also: ~
+      • |nvim_get_commands()|
+
 nvim_get_option_info2({name}, {*opts})               *nvim_get_option_info2()*
     Gets the option information for one option from arbitrary buffer or window
 
@@ -3238,8 +3244,8 @@ nvim_tabpage_set_var({tabpage}, {name}, {value})
 Autocmd Functions                                                *api-autocmd*
 
 nvim_clear_autocmds({*opts})                           *nvim_clear_autocmds()*
-    Clear all autocommands that match the corresponding {opts}. To delete a
-    particular autocmd, see |nvim_del_autocmd()|.
+    Clears all autocommands selected by {opts}. To delete autocmds see
+    |nvim_del_autocmd()|.
 
     Parameters: ~
       • {opts}  Parameters
@@ -3381,15 +3387,10 @@ nvim_del_augroup_by_name({name})                  *nvim_del_augroup_by_name()*
       • |autocmd-groups|
 
 nvim_del_autocmd({id})                                    *nvim_del_autocmd()*
-    Delete an autocommand by id.
-
-    NOTE: Only autocommands created via the API have an id.
+    Deletes an autocommand by id.
 
     Parameters: ~
-      • {id}  Integer The id returned by nvim_create_autocmd
-
-    See also: ~
-      • |nvim_create_autocmd()|
+      • {id}  Integer Autocommand id returned by |nvim_create_autocmd()|
 
 nvim_exec_autocmds({event}, {*opts})                    *nvim_exec_autocmds()*
     Execute all autocommands for {event} that match the corresponding {opts}
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index f36ef1df0a..b3f7d1fadc 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -132,7 +132,7 @@ DOCUMENTATION						*dev-doc*
   optimize for the reader's time and energy: be "precise yet concise".
     - Prefer the active voice: "Foo does X", not "X is done by Foo".
     - "The words you choose are an essential part of the user experience."
-      https://developer.apple.com/design/human-interface-guidelines/foundations/writing/
+      https://developer.apple.com/design/human-interface-guidelines/writing
     - "...without being overly colloquial or frivolous."
       https://developers.google.com/style/tone
 - Write docstrings (as opposed to inline comments) with present tense ("Gets"),
@@ -226,6 +226,7 @@ Lua documentation lives in the source code, as docstrings on the function
 definitions.  The |lua-vim| :help is generated from the docstrings.
 
 Docstring format:
+- Use LuaLS annotations: https://github.com/LuaLS/lua-language-server/wiki/Annotations
 - Lines in the main description start with `---`
 - Special tokens start with `---@` followed by the token name:
   `---@see`, `---@param`, `---@returns`
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 32dcd930bb..94a2c0d45e 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -70,6 +70,17 @@ https://www.lua.org/doc/cacm2018.pdf
 - Stackful coroutines enable cooperative multithreading, generators, and
   versatile control for both Lua and its host (Nvim).
 
+                                                           *iterator*
+An iterator is just a function that can be called repeatedly to get the "next"
+value of a collection (or any other |iterable|). This interface is expected by
+|for-in| loops, produced by |pairs()|, supported by |vim.iter|, etc.
+https://www.lua.org/pil/7.1.html
+
+                                                           *iterable*
+An "iterable" is anything that |vim.iter()| can consume: tables, dicts, lists,
+iterator functions, tables implementing the |__call()| metamethod, and
+|vim.iter()| objects.
+
                                                            *lua-call-function*
 Lua functions can be called in multiple ways. Consider the function: >lua
     local foo = function(a, b)
@@ -1558,7 +1569,7 @@ vim.deprecate({name}, {alternative}, {version}, {plugin}, {backtrace})
       • {backtrace}    boolean|nil Prints backtrace. Defaults to true.
 
     Return: ~
-        (string|nil) # Deprecated message, or nil if no message was shown.
+        (string|nil) Deprecated message, or nil if no message was shown.
 
 vim.inspect                                                    *vim.inspect()*
     Gets a human-readable representation of the given object.
@@ -1682,7 +1693,7 @@ vim.print({...})                                                 *vim.print()*
 <
 
     Return: ~
-        any # given arguments.
+        any given arguments.
 
     See also: ~
       • |vim.inspect()|
@@ -1909,7 +1920,8 @@ vim.endswith({s}, {suffix})                                   *vim.endswith()*
         (boolean) `true` if `suffix` is a suffix of `s`
 
 vim.gsplit({s}, {sep}, {opts})                                  *vim.gsplit()*
-    Splits a string at each instance of a separator.
+    Gets an |iterator| that splits a string at each instance of a separator,
+    in "lazy" fashion (as opposed to |vim.split()| which is "eager").
 
     Example: >lua
 
@@ -2065,7 +2077,7 @@ vim.spairs({t})                                                 *vim.spairs()*
     Enumerate a table sorted by its keys.
 
     Parameters: ~
-      • {t}  (table) List-like table
+      • {t}  (table) Dict-like table
 
     Return: ~
         iterator over sorted keys and their values
@@ -2074,7 +2086,8 @@ vim.spairs({t})                                                 *vim.spairs()*
       • Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua
 
 vim.split({s}, {sep}, {opts})                                    *vim.split()*
-    Splits a string at each instance of a separator.
+    Splits a string at each instance of a separator and returns the result as
+    a table (unlike |vim.gsplit()|).
 
     Examples: >lua
 
@@ -2532,8 +2545,8 @@ vim.ui.open({path})                                            *vim.ui.open()*
       • {path}  (string) Path or URL to open
 
     Return (multiple): ~
-        SystemCompleted|nil # Command result, or nil if not found.
-        (string|nil) # Error message on failure
+        SystemCompleted|nil Command result, or nil if not found.
+        (string|nil) Error message on failure
 
     See also: ~
       • |vim.system()|
@@ -3192,22 +3205,19 @@ vim.version.range({spec})                                *vim.version.range()*
 Lua module: vim.iter                                                *vim.iter*
 
 
-This module provides a generic interface for working with iterables:
-tables, lists, iterator functions, pair()/ipair()-like iterators, and
-`vim.iter()` objects.
-
-*vim.iter()* wraps its table or function argument into an *Iter* object
-with methods (such as |Iter:filter()| and |Iter:map()|) that transform the
-underlying source data. These methods can be chained together to create
-iterator "pipelines". Each pipeline stage receives as input the output
-values from the prior stage. The values used in the first stage of the
-pipeline depend on the type passed to this function:
+*vim.iter()* is an interface for |iterable|s: it wraps a table or function
+argument into an *Iter* object with methods (such as |Iter:filter()| and
+|Iter:map()|) that transform the underlying source data. These methods can
+be chained together to create iterator "pipelines". Each pipeline stage
+receives as input the output values from the prior stage. The values used
+in the first stage of the pipeline depend on the type passed to this
+function:
 
 • List tables pass only the value of each element
-• Non-list tables pass both the key and value of each element
-• Function iterators pass all of the values returned by their respective
+• Non-list (dict) tables pass both the key and value of each element
+• Function |iterator|s pass all of the values returned by their respective
   function
-• Tables with a metatable implementing __call are treated as function
+• Tables with a metatable implementing |__call()| are treated as function
   iterators
 
 Examples: >lua
diff --git a/runtime/doc/luaref.txt b/runtime/doc/luaref.txt
index a5b9e433ed..1096759ad8 100644
--- a/runtime/doc/luaref.txt
+++ b/runtime/doc/luaref.txt
@@ -437,7 +437,7 @@ middle of a block, then an explicit inner block can be used, as in the idioms
 the last statements in their (inner) blocks.
 
 ------------------------------------------------------------------------------
-2.4.5  For Statement                             *luaref-for* *luaref-langForStat*
+2.4.5  For Statement                             *for* *luaref-langForStat*
 
 The `for` statement has two forms: one numeric and one generic.
 
@@ -477,8 +477,8 @@ Note the following:
    after the `for` ends or is broken. If you need this value, assign it to
    another variable before breaking or exiting the loop.
 
-                                                                     *luaref-in*
-The generic `for` statement works over functions, called iterators. On each
+                                                                      *for-in*
+The generic `for` statement works over functions, called |iterator|s. On each
 iteration, the iterator function is called to produce a new value, stopping
 when this new value is `nil`. The generic `for` loop has the following syntax:
 >
@@ -3611,8 +3611,8 @@ getmetatable({object})                                   *luaref-getmetatable()*
         associated value. Otherwise, returns the metatable of the given
         object.
 
-ipairs({t})                                                    *luaref-ipairs()*
-        Returns three values: an iterator function, the table {t}, and 0, so
+ipairs({t})                                                           *ipairs()*
+        Returns three values: an |iterator| function, the table {t}, and 0, so
         that the construction
 
                `for i,v in ipairs(t) do`  `body`  `end`
@@ -3645,7 +3645,7 @@ loadstring({string} [, {chunkname}])                       *luaref-loadstring()*
                assert(loadstring(s))()
 <
 
-next({table} [, {index}])                                        *luaref-next()*
+next({table} [, {index}])                                        *next()*
         Allows a program to traverse all fields of a table. Its first argument
         is a table and its second argument is an index in this table. `next`
         returns the next index of the table and its associated value. When
@@ -3657,15 +3657,15 @@ next({table} [, {index}])                                        *luaref-next()*
 
         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` |luaref-ipairs()| function.)
+        numerical `for` or the |ipairs()| function.)
 
         The behavior of `next` is `undefined` if, during the traversal, you
         assign any value to a non-existent field in the table. You may however
         modify existing fields. In particular, you may clear existing fields.
 
-pairs({t})                                                      *luaref-pairs()*
-        Returns three values: the `next` |luaref-next()| function, the table
-        {t}, and `nil`, so that the construction
+pairs({t})                                                             *pairs()*
+        Returns three values: the |next()| function, the table {t}, and `nil`,
+        so that the construction
 
                `for k,v in pairs(t) do`  `body`  `end`
 
@@ -3826,7 +3826,7 @@ coroutine.wrap({f})                                           *coroutine.wrap()*
 
 coroutine.yield({...})                                       *coroutine.yield()*
         Suspends the execution of the calling coroutine. The coroutine cannot
-        be running a C function, a metamethod, or an iterator. Any arguments
+        be running a C function, a metamethod, or an |iterator|. Any arguments
         to `yield` are passed as extra results to `resume`.
 
 ==============================================================================
@@ -4036,7 +4036,7 @@ string.format({formatstring}, {...})                           *string.format()*
         This function does not accept string values containing embedded zeros.
 
 string.gmatch({s}, {pattern})                                  *string.gmatch()*
-        Returns an iterator function that, each time it is called, returns the
+        Returns an |iterator| function that, each time it is called, returns the
         next captures from {pattern} over string {s}.
 
         If {pattern} specifies no captures, then the whole match is produced
@@ -4271,7 +4271,7 @@ table.foreach({table}, {f})                                    *table.foreach()*
         returns a non-`nil` value, then the loop is broken, and this value is
         returned as the final value of `table.foreach`.
 
-        See |luaref-next()| for extra information about table traversals.
+        See |next()| for extra information about table traversals.
 
 table.foreachi({table}, {f})                                  *table.foreachi()*
         Executes the given {f} over the numerical indices of {table}. For each
@@ -4464,7 +4464,7 @@ io.input([{file}])                                                  *io.input()*
         an error code.
 
 io.lines([{filename}])                                              *io.lines()*
-        Opens the given file name in read mode and returns an iterator
+        Opens the given file name in read mode and returns an |iterator|
         function that, each time it is called, returns a new line from the
         file. Therefore, the construction
 
@@ -4533,7 +4533,7 @@ file:flush()                                               *luaref-file:flush()*
         Saves any written data to `file`.
 
 file:lines()                                               *luaref-file:lines()*
-        Returns an iterator function that, each time it is called, returns a
+        Returns an |iterator| function that, each time it is called, returns a
         new line from the file. Therefore, the construction
 
                `for line in file:lines() do`  `body`  `end`
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index c3fec85163..2d56fc4fc4 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -71,7 +71,7 @@ The following new APIs and features were added.
     https://github.com/neovim/neovim/pull/23611
 
 • |vim.iter()| provides a generic iterator interface for tables and Lua
-  iterators |luaref-in|.
+  iterators |for-in|.
 
 • Added |vim.ringbuf()| to create ring buffers.
 
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index 956c37fc0f..52e8f4d86c 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -495,6 +495,9 @@ user command or autocommand, the script in which it was defined is reported.
 <			- When 'keywordprg' is equal to "man -s", a [count]
 			  before "K" is inserted after the "-s".  If there is
 			  no count, the "-s" is removed.
+							       *K-lsp-default*
+			- The Nvim |LSP| client sets K to show LSP "hover"
+			  feature. |lsp-defaults|
 
 							*v_K*
 {Visual}K		Like "K", but use the visually highlighted text for
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 1230769c1a..be187f842a 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -115,13 +115,15 @@ DEFAULT MAPPINGS
 Nvim creates the following default mappings at |startup|. You can disable any
 of these in your config by simply removing the mapping, e.g. ":unmap Y".
 
-- |Y-default|
-- |i_CTRL-U-default|
-- |i_CTRL-W-default|
-- |CTRL-L-default|
-- |&-default|
-- |v_#-default|
-- |v_star-default|
+- Y |Y-default|
+- <C-U> |i_CTRL-U-default|
+- <C-W> |i_CTRL-W-default|
+- <C-L> |CTRL-L-default|
+- & |&-default|
+- # |v_#-default|
+- * |v_star-default|
+- Nvim LSP client defaults |lsp-defaults|
+  - K |K-lsp-default|
 
 DEFAULT AUTOCOMMANDS
 							*default-autocmds*
@@ -511,6 +513,9 @@ 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
@@ -732,9 +737,6 @@ Options:
   *'ttytype'* *'tty'*
   weirdinvert
 
-Performance:
-  Folds are not updated during insert-mode.
-
 Plugins:
 
 - logiPat
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 3622ba5d19..c0e4e35e7d 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -691,8 +691,8 @@ function vim.api.nvim_call_function(fn, args) end
 --- @param data string data to write. 8-bit clean: can contain NUL bytes.
 function vim.api.nvim_chan_send(chan, data) end
 
---- Clear all autocommands that match the corresponding {opts}. To delete a
---- particular autocmd, see `nvim_del_autocmd()`.
+--- Clears all autocommands selected by {opts}. To delete autocmds see
+--- `nvim_del_autocmd()`.
 ---
 --- @param opts vim.api.keyset.clear_autocmds Parameters
 ---             • event: (string|table) Examples:
@@ -919,10 +919,9 @@ function vim.api.nvim_del_augroup_by_id(id) end
 --- @param name string String The name of the group.
 function vim.api.nvim_del_augroup_by_name(name) end
 
---- Delete an autocommand by id.
---- NOTE: Only autocommands created via the API have an id.
+--- Deletes an autocommand by id.
 ---
---- @param id integer Integer The id returned by nvim_create_autocmd
+--- @param id integer Integer Autocommand id returned by `nvim_create_autocmd()`
 function vim.api.nvim_del_autocmd(id) end
 
 --- Deletes the current line.
diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 7bffcc9c20..a278e96a5f 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -1,22 +1,15 @@
 ---@defgroup vim.iter
 ---
---- This module provides a generic interface for working with
---- iterables: tables, lists, iterator functions, pair()/ipair()-like iterators,
---- and \`vim.iter()\` objects.
----
---- \*vim.iter()\* wraps its table or function argument into an \*Iter\* object
---- with methods (such as |Iter:filter()| and |Iter:map()|) that transform the
---- underlying source data. These methods can be chained together to create
---- iterator "pipelines". Each pipeline stage receives as input the output
---- values from the prior stage. The values used in the first stage of the
---- pipeline depend on the type passed to this function:
+--- \*vim.iter()\* is an interface for |iterable|s: it wraps a table or function argument into an
+--- \*Iter\* object with methods (such as |Iter:filter()| and |Iter:map()|) that transform the
+--- underlying source data. These methods can be chained together to create iterator "pipelines".
+--- Each pipeline stage receives as input the output values from the prior stage. The values used in
+--- the first stage of the pipeline depend on the type passed to this function:
 ---
 --- - List tables pass only the value of each element
---- - Non-list tables pass both the key and value of each element
---- - Function iterators pass all of the values returned by their respective
----   function
---- - Tables with a metatable implementing __call are treated as function
----   iterators
+--- - Non-list (dict) tables pass both the key and value of each element
+--- - Function |iterator|s pass all of the values returned by their respective function
+--- - Tables with a metatable implementing |__call()| are treated as function iterators
 ---
 --- Examples:
 --- <pre>lua
diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 291b003d87..5ce5b200d3 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -60,7 +60,8 @@ function vim.deepcopy(orig)
   return deepcopy(orig)
 end
 
---- Splits a string at each instance of a separator.
+--- Gets an |iterator| that splits a string at each instance of a separator, in "lazy" fashion
+--- (as opposed to |vim.split()| which is "eager").
 ---
 --- Example:
 ---   <pre>lua
@@ -159,7 +160,8 @@ function vim.gsplit(s, sep, opts)
   end
 end
 
---- Splits a string at each instance of a separator.
+--- Splits a string at each instance of a separator and returns the result as a table (unlike
+--- |vim.gsplit()|).
 ---
 --- Examples:
 --- <pre>lua
@@ -530,8 +532,8 @@ end
 ---
 ---@see Based on https://github.com/premake/premake-core/blob/master/src/base/table.lua
 ---
----@param t table List-like table
----@return iterator over sorted keys and their values
+---@param t table Dict-like table
+---@return # iterator over sorted keys and their values
 function vim.spairs(t)
   assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))