docs: misc

Co-authored-by: Kevin Pham <keevan.pham@gmail.com>

CONTRIBUTING.md

@@ -304,14 +304,10 @@ Lua documentation uses a subset of [EmmyLua] annotations. See [:help dev-doc-lua
   ---@return type {description}
   ```
 - If possible, add type information (`table`, `string`, `number`, ...). Multiple valid types are separated by a bar (`string|table`). Indicate optional parameters via `type|nil`.
-- If a function in your Lua module should _not_ be documented (e.g. internal or local function), set the doc comment to:
+- If a function in your Lua module should _not_ be documented, add `@nodoc`.
-  ```
+- If the function is internal or otherwise non-public add `@private`.
-  ---@private
+      - Private functions usually should be underscore-prefixed (named "_foo", not "foo").
-  ```
+- Mark deprecated functions with `@deprecated`.
-- Mark deprecated functions with:
-  ```
-  ---@deprecated
-  ```
 
 Reviewing
 ---------

MAINTAIN.md

@@ -131,41 +131,46 @@ We may maintain forks, if we are waiting on upstream changes: https://github.com
 Non-technical dependencies
 --------------------------
 
+* GitHub users:
+    * https://github.com/marvim
+    * https://github.com/nvim-winget
 * Domain names (held in https://namecheap.com):
     * neovim.org
     * neovim.io
     * packspec.org
     * pkgjson.org
+* DNS for the above domains is managed in https://cloudflare.com (not the domain registrar)
 
 Automation (CI)
 ---------------
 
-Our CI and automation jobs are primarily driven by GitHub Actions. Guidelines:
+### Backup
 
-### General
+Discussions from issues and PRs are backed up here:
+https://github.com/neovim/neovim-backup
 
+### Development guidelines
+
+* CI and automation jobs are primarily driven by GitHub Actions.
 * Avoid macOS if an Ubuntu or a Windows runner can be used instead. This is
   because macOS runners have [tighter restrictions on the number of concurrent
   jobs](https://docs.github.com/en/actions/learn-github-actions/usage-limits-billing-and-administration#usage-limits).
 
-### Runner versions
+* Runner versions:
-
+    * For special-purpose jobs where the runner version doesn't really matter,
-* For special-purpose jobs where the runner version doesn't really matter,
       prefer `-latest` tags so we don't need to manually bump the versions. An
       example of a special-purpose workflow is `labeler.yml`.
-
+    * For our testing jobs, which are in `test.yml` and `build.yml`, prefer to
-* For our testing jobs, which are in `test.yml` and `build.yml`, prefer to use
+      use the latest stable (i.e. non-beta) version explicitly. Avoid using the
-  the latest stable (i.e. non-beta) version explicitly. Avoid using the
+      `-latest` tags here as it makes it difficult to determine from an
-  `-latest` tags here as it makes it difficult to determine from an unrelated
+      unrelated PR if a failure is due to the PR itself or due to GitHub bumping
-  PR if a failure is due to the PR itself or due to GitHub bumping the
+      the `-latest` tag without our knowledge. There's also a high risk that
-  `-latest` tag without our knowledge. There's also a high risk that automatic
+      automatically bumping the CI versions will fail due to manual work being
-  bumping the CI versions will fail due to manual work being required from
+      required from experience.
-  experience.
+    * For our release job, which is `release.yml`, prefer to use the oldest
-
+      stable (i.e. non-deprecated) versions available. The reason is that we're
-* For our release job, which is `release.yml`, prefer to use the oldest stable
+      trying to produce images that work in the broadest number of environments,
-  (i.e. non-deprecated) versions available. The reason is that we're trying to
+      and therefore want to use older releases.
-  produce images that work in the broadest number of environments, and
-  therefore want to use older releases.
 
 See also
 --------

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
+    Clears all autocommands selected by {opts}. To delete autocmds see
-    particular autocmd, see |nvim_del_autocmd()|.
+    |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.
+    Deletes an autocommand by id.
-
-    NOTE: Only autocommands created via the API have an id.
 
     Parameters: ~
-      • {id}  Integer The id returned by nvim_create_autocmd
+      • {id}  Integer Autocommand id returned by |nvim_create_autocmd()|
-
-    See also: ~
-      • |nvim_create_autocmd()|
 
 nvim_exec_autocmds({event}, {*opts})                    *nvim_exec_autocmds()*
     Execute all autocommands for {event} that match the corresponding {opts}

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"),

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)
@@ -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,16 +2077,17 @@ 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
+        _ iterator over sorted keys and their values
 
     See also: ~
       • 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
 
@@ -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:
+*vim.iter()* is an interface for |iterable|s: it wraps a table or function
-tables, lists, iterator functions, pair()/ipair()-like iterators, and
+argument into an *Iter* object with methods (such as |Iter:filter()| and
-`vim.iter()` objects.
+|Iter:map()|) that transform the underlying source data. These methods can
-
+be chained together to create iterator "pipelines". Each pipeline stage
-*vim.iter()* wraps its table or function argument into an *Iter* object
+receives as input the output values from the prior stage. The values used
-with methods (such as |Iter:filter()| and |Iter:map()|) that transform the
+in the first stage of the pipeline depend on the type passed to this
-underlying source data. These methods can be chained together to create
+function:
-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
+• Non-list (dict) tables pass both the key and value of each element
-• Function iterators pass all of the values returned by their respective
+• 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

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*
+                                                                      *for-in*
-The generic `for` statement works over functions, called iterators. On each
+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()*
+ipairs({t})                                                           *ipairs()*
-        Returns three values: an iterator function, the table {t}, and 0, so
+        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()*
+pairs({t})                                                             *pairs()*
-        Returns three values: the `next` |luaref-next()| function, the table
+        Returns three values: the |next()| function, the table {t}, and `nil`,
-        {t}, and `nil`, so that the construction
+        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`

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.
 

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

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|
+- Y |Y-default|
-- |i_CTRL-U-default|
+- <C-U> |i_CTRL-U-default|
-- |i_CTRL-W-default|
+- <C-W> |i_CTRL-W-default|
-- |CTRL-L-default|
+- <C-L> |CTRL-L-default|
-- |&-default|
+- & |&-default|
-- |v_#-default|
+- # |v_#-default|
-- |v_star-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

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
+--- Clears all autocommands selected by {opts}. To delete autocmds see
---- particular autocmd, see `nvim_del_autocmd()`.
+--- `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.
+--- Deletes an autocommand by id.
---- NOTE: Only autocommands created via the API have an 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.

runtime/lua/vim/iter.lua

@@ -1,22 +1,15 @@
 ---@defgroup vim.iter
 ---
---- This module provides a generic interface for working with
+--- \*vim.iter()\* is an interface for |iterable|s: it wraps a table or function argument into an
---- iterables: tables, lists, iterator functions, pair()/ipair()-like iterators,
+--- \*Iter\* object with methods (such as |Iter:filter()| and |Iter:map()|) that transform the
---- and \`vim.iter()\` objects.
+--- 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
---- \*vim.iter()\* wraps its table or function argument into an \*Iter\* object
+--- the first stage of the pipeline depend on the type passed to this function:
---- 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
+--- - Non-list (dict) tables pass both the key and value of each element
---- - Function iterators pass all of the values returned by their respective
+--- - Function |iterator|s pass all of the values returned by their respective function
----   function
+--- - Tables with a metatable implementing |__call()| are treated as function iterators
---- - Tables with a metatable implementing __call are treated as function
----   iterators
 ---
 --- Examples:
 --- <pre>lua

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
+---@param t table Dict-like table
----@return iterator over sorted keys and their values
+---@return # iterator over sorted keys and their values
 function vim.spairs(t)
   assert(type(t) == 'table', string.format('Expected table, got %s', type(t)))
 

src/nvim/api/autocmd.c

@@ -517,11 +517,9 @@ cleanup:
   return autocmd_id;
 }
 
-/// Delete an autocommand by id.
+/// Deletes an autocommand by id.
 ///
-/// NOTE: Only autocommands created via the API have an id.
+/// @param id Integer Autocommand id returned by |nvim_create_autocmd()|
-/// @param id Integer The id returned by nvim_create_autocmd
-/// @see |nvim_create_autocmd()|
 void nvim_del_autocmd(Integer id, Error *err)
   FUNC_API_SINCE(9)
 {
@@ -533,8 +531,8 @@ void nvim_del_autocmd(Integer id, Error *err)
   }
 }
 
-/// Clear all autocommands that match the corresponding {opts}. To delete
+/// Clears all autocommands selected by {opts}. To delete autocmds see |nvim_del_autocmd()|.
-/// a particular autocmd, see |nvim_del_autocmd()|.
+///
 /// @param opts Parameters
 ///         - event: (string|table)
 ///              Examples:

src/nvim/api/command.c

@@ -1230,6 +1230,8 @@ err:
 ///
 /// Currently only |user-commands| are supported, not builtin Ex commands.
 ///
+/// @see |nvim_get_all_options_info()|
+///
 /// @param  opts  Optional parameters. Currently only supports
 ///               {"builtin":false}
 /// @param[out]  err   Error details, if any.

src/nvim/api/options.c

@@ -315,6 +315,8 @@ void nvim_set_option_value(uint64_t channel_id, String name, Object value, Dict(
 /// The dictionary has the full option names as keys and option metadata
 /// dictionaries as detailed at |nvim_get_option_info2()|.
 ///
+/// @see |nvim_get_commands()|
+///
 /// @return dictionary of all options
 Dictionary nvim_get_all_options_info(Error *err)
   FUNC_API_SINCE(7)