docs: various #25289

Co-authored-by: Jongwook Choi <wookayin@gmail.com>
Co-authored-by: Oliver Marriott <hello@omarriott.com>
Co-authored-by: Benoit de Chezelles <bew@users.noreply.github.com>
Co-authored-by: Jongwook Choi <wookayin@gmail.com>

12 files changed, 67 insertions, 38 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3fe735cad2..ef83c22155 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -149,8 +149,10 @@ View the [Clang report] to see potential bugs found by the Clang
 
 ### Coverity
 
-[Coverity](https://scan.coverity.com/projects/neovim-neovim) runs against the
-master build. To view the defects, just request access; you will be approved.
+Coverity runs against the master build. To view the defects you must
+[request access](https://scan.coverity.com/projects/neovim-neovim) (Coverity
+does not have a "public" view), then you will be approved as soon as
+a maintainer sees the email.
 
 - Use this format for commit messages (where `{id}` is the CID (Coverity ID);
   ([example](https://github.com/neovim/neovim/pull/804))):
@@ -283,7 +285,7 @@ If you need to modify or debug the documentation flow, these are the main files:
 ### Lua docstrings
 
 Use [LuaLS] annotations in Lua docstrings to annotate parameter types, return
-types, etc. See [:help dev-doc-lua][dev-doc-lua].
+types, etc. See [:help dev-lua-doc][dev-lua-doc].
 
 - The template for function documentation is:
   ```lua
@@ -331,8 +333,8 @@ as context, use the `-W` argument as well.
 [complexity:low]: https://github.com/neovim/neovim/issues?q=is%3Aopen+is%3Aissue+label%3Acomplexity%3Alow
 [conventional_commits]: https://www.conventionalcommits.org
 [dev-doc-guide]: https://neovim.io/doc/user/develop.html#dev-doc
-[dev-doc-lua]: https://neovim.io/doc/user/develop.html#dev-lua-doc
-[LuaLS]: https://github.com/LuaLS/lua-language-server/wiki/Annotations
+[dev-lua-doc]: https://neovim.io/doc/user/develop.html#dev-lua-doc
+[LuaLS]: https://luals.github.io/wiki/annotations/
 [gcc-warnings]: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html
 [gh]: https://cli.github.com/
 [git-bisect]: http://git-scm.com/book/en/v2/Git-Tools-Debugging-with-Git
diff --git a/cmake.deps/CMakeLists.txt b/cmake.deps/CMakeLists.txt
index 90b752d250..afc4da8def 100644
--- a/cmake.deps/CMakeLists.txt
+++ b/cmake.deps/CMakeLists.txt
@@ -37,6 +37,7 @@ option(USE_BUNDLED "Use bundled dependencies." ON)
 option(USE_BUNDLED_LIBUV "Use the bundled libuv." ${USE_BUNDLED})
 option(USE_BUNDLED_LIBVTERM "Use the bundled libvterm." ${USE_BUNDLED})
 option(USE_BUNDLED_LPEG "Use the bundled lpeg." ${USE_BUNDLED})
+# PUC Lua is only used for tests, unless explicitly requested.
 option(USE_BUNDLED_LUA "Use the bundled version of lua." OFF)
 option(USE_BUNDLED_LUAJIT "Use the bundled version of luajit." ${USE_BUNDLED})
 option(USE_BUNDLED_LUV "Use the bundled version of luv." ${USE_BUNDLED})
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index ce3af01073..e43574fe86 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -784,9 +784,6 @@ OptionSet			After setting an option (except during
 				are not global-local it is the old local
 				value.
 
-				OptionSet is not triggered on startup and for
-				the 'key' option for obvious reasons.
-
 				Usage example: Check for the existence of the
 				directory in the 'backupdir' and 'undodir'
 				options, create the directory if it doesn't
@@ -800,6 +797,8 @@ OptionSet			After setting an option (except during
 				Non-recursive: |:set| in the autocommand does
 				not trigger OptionSet again.
 
+				Not triggered on startup.
+
 							*QuickFixCmdPre*
 QuickFixCmdPre			Before a quickfix command is run (|:make|,
 				|:lmake|, |:grep|, |:lgrep|, |:grepadd|,
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index e3fc616df4..ad1b838578 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -911,9 +911,8 @@ start({config}, {opts})                                      *vim.lsp.start()*
 
     • `name` arbitrary name for the LSP client. Should be unique per language
       server.
-    • `cmd` command (in list form) used to start the language server. Must be
-      absolute, or found on `$PATH`. Shell constructs like `~` are not
-      expanded.
+    • `cmd` command string[] or function, described at
+      |vim.lsp.start_client()|.
     • `root_dir` path to the project root. By default this is used to decide
       if an existing client should be re-used. The example above uses
       |vim.fs.find()| and |vim.fs.dirname()| to detect the root by traversing
@@ -953,15 +952,16 @@ start_client({config})                                *vim.lsp.start_client()*
 
     Parameters: ~
       • {config}  (`lsp.ClientConfig`) Configuration for the server:
-                  • cmd: (string[]|fun(dispatchers: table):table) command a
-                    list of strings treated like |jobstart()|. The command
-                    must launch the language server process. `cmd` can also be
-                    a function that creates an RPC client. The function
-                    receives a dispatchers table and must return a table with
-                    the functions `request`, `notify`, `is_closing` and
-                    `terminate` See |vim.lsp.rpc.request()| and
-                    |vim.lsp.rpc.notify()| For TCP there is a built-in rpc
-                    client factory: |vim.lsp.rpc.connect()|
+                  • cmd: (string[]|fun(dispatchers: table):table) command
+                    string[] that launches the language server (treated as in
+                    |jobstart()|, must be absolute or on `$PATH`, shell
+                    constructs like "~" are not expanded), or function that
+                    creates an RPC client. Function receives a `dispatchers`
+                    table and returns a table with member functions `request`,
+                    `notify`, `is_closing` and `terminate`. See
+                    |vim.lsp.rpc.request()|, |vim.lsp.rpc.notify()|. For TCP
+                    there is a builtin RPC client factory:
+                    |vim.lsp.rpc.connect()|
                   • cmd_cwd: (string, default=|getcwd()|) Directory to launch
                     the `cmd` process. Not related to `root_dir`.
                   • cmd_env: (table) Environment flags to pass to the LSP on
@@ -1479,7 +1479,11 @@ save({lenses}, {bufnr}, {client_id})                 *vim.lsp.codelens.save()*
 Lua module: vim.lsp.inlay_hint                                *lsp-inlay_hint*
 
 enable({bufnr}, {enable})                        *vim.lsp.inlay_hint.enable()*
-    Enable/disable/toggle inlay hints for a buffer
+    Enables or disables inlay hints for a buffer.
+
+    To "toggle", pass the inverse of `is_enabled()`: >lua
+        vim.lsp.inlay_hint.enable(0, not vim.lsp.inlay_hint.is_enabled())
+<
 
     Note: ~
         This API is pre-release (unstable).
diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt
index 03fe5c7b81..e80969c583 100644
--- a/runtime/doc/motion.txt
+++ b/runtime/doc/motion.txt
@@ -1048,7 +1048,7 @@ CTRL-I			Go to [count] newer cursor position in jump list
 			|tui-modifyOtherKeys| or |tui-csiu|, CTRL-I can be
 			mapped separately from <Tab>, on the condition that
 			both keys are mapped, otherwise the mapping applies to
-			both.
+			both. Except in tmux: https://github.com/tmux/tmux/issues/2705
 
 							*:ju* *:jumps*
 :ju[mps]		Print the jump list (not a motion command).
diff --git a/runtime/doc/recover.txt b/runtime/doc/recover.txt
index e6b5b06744..4312716b22 100644
--- a/runtime/doc/recover.txt
+++ b/runtime/doc/recover.txt
@@ -85,10 +85,10 @@ You can find this in the user manual, section |11.3|.
 
 									*W325*
 The default |SwapExists| handler (|default-autocmds|) skips the |E325| prompt
-(selects "(E)dit") if the swapfile owner process (1) is still running and (2)
-was started by the current user.  This presumes that you normally don't want
-to be bothered with the |ATTENTION| message just because you happen to edit
-the same file from multiple Nvim instances.  In the worst case (a system
+(and automatically chooses "(E)dit") if the swapfile owner process is still
+running and owned by the current user.  This presumes that you normally don't
+want to be bothered with the |ATTENTION| message just because you happen to
+edit the same file from multiple Nvim instances.  In the worst case (a system
 crash) there will be more than one swapfile for the file; use |:recover| to
 inspect all of its swapfiles.
 
diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua
index a02a93d559..f3448209ba 100644
--- a/runtime/lua/vim/lsp.lua
+++ b/runtime/lua/vim/lsp.lua
@@ -488,8 +488,7 @@ end
 --- See |vim.lsp.start_client()| for all available options. The most important are:
 ---
 --- - `name` arbitrary name for the LSP client. Should be unique per language server.
---- - `cmd` command (in list form) used to start the language server. Must be absolute, or found on
----   `$PATH`. Shell constructs like `~` are not expanded.
+--- - `cmd` command string[] or function, described at |vim.lsp.start_client()|.
 --- - `root_dir` path to the project root. By default this is used to decide if an existing client
 ---   should be re-used. The example above uses |vim.fs.find()| and |vim.fs.dirname()| to detect the
 ---   root by traversing the file system upwards starting from the current directory until either
@@ -666,13 +665,13 @@ end
 --- Field `cmd` in {config} is required.
 ---
 ---@param config (lsp.ClientConfig) Configuration for the server:
---- - cmd: (string[]|fun(dispatchers: table):table) command a list of
----       strings treated like |jobstart()|. The command must launch the language server
----       process. `cmd` can also be a function that creates an RPC client.
----       The function receives a dispatchers table and must return a table with the
----       functions `request`, `notify`, `is_closing` and `terminate`
----       See |vim.lsp.rpc.request()| and |vim.lsp.rpc.notify()|
----       For TCP there is a built-in rpc client factory: |vim.lsp.rpc.connect()|
+--- - cmd: (string[]|fun(dispatchers: table):table) command string[] that launches the language
+---       server (treated as in |jobstart()|, must be absolute or on `$PATH`, shell constructs like
+---       "~" are not expanded), or function that creates an RPC client. Function receives
+---       a `dispatchers` table and returns a table with member functions `request`, `notify`,
+---       `is_closing` and `terminate`.
+---       See |vim.lsp.rpc.request()|, |vim.lsp.rpc.notify()|.
+---       For TCP there is a builtin RPC client factory: |vim.lsp.rpc.connect()|
 ---
 --- - cmd_cwd: (string, default=|getcwd()|) Directory to launch
 ---       the `cmd` process. Not related to `root_dir`.
diff --git a/runtime/lua/vim/lsp/inlay_hint.lua b/runtime/lua/vim/lsp/inlay_hint.lua
index ce1680549e..4816b873ba 100644
--- a/runtime/lua/vim/lsp/inlay_hint.lua
+++ b/runtime/lua/vim/lsp/inlay_hint.lua
@@ -368,7 +368,13 @@ function M.is_enabled(bufnr)
   return bufstates[bufnr] and bufstates[bufnr].enabled or false
 end
 
---- Enable/disable/toggle inlay hints for a buffer
+--- Enables or disables inlay hints for a buffer.
+---
+--- To "toggle", pass the inverse of `is_enabled()`:
+---
+--- ```lua
+--- vim.lsp.inlay_hint.enable(0, not vim.lsp.inlay_hint.is_enabled())
+--- ```
 ---
 --- @param bufnr (integer|nil) Buffer handle, or 0 or nil for current
 --- @param enable (boolean|nil) true/nil to enable, false to disable
diff --git a/src/nvim/README.md b/src/nvim/README.md
index b264c918b6..9ef39cc90f 100644
--- a/src/nvim/README.md
+++ b/src/nvim/README.md
@@ -255,6 +255,12 @@ region is repainted internally. To also highlight excess internal redraws, use
 - http://bazaar.launchpad.net/~libvterm/libvterm/trunk/view/head:/doc/seqs.txt
 - http://invisible-island.net/xterm/ctlseqs/ctlseqs.html
 
+Data structures
+---------------
+
+Buffer text is stored as a tree of line segments, defined in [memline.c](https://github.com/neovim/neovim/blob/v0.9.5/src/nvim/memline.c#L8-L35).
+The central idea is found in [ml_find_line](https://github.com/neovim/neovim/blob/v0.9.5/src/nvim/memline.c#L2800).
+
 Nvim lifecycle
 --------------
 
diff --git a/src/nvim/tui/tui.c b/src/nvim/tui/tui.c
index 9cd0c64bfe..6b8b73a2a0 100644
--- a/src/nvim/tui/tui.c
+++ b/src/nvim/tui/tui.c
@@ -1312,6 +1312,9 @@ void tui_default_colors_set(TUIData *tui, Integer rgb_fg, Integer rgb_bg, Intege
   invalidate(tui, 0, tui->grid.height, 0, tui->grid.width);
 }
 
+/// Flushes TUI grid state to a buffer (which is later flushed to the TTY by `flush_buf`).
+///
+/// @see flush_buf
 void tui_flush(TUIData *tui)
 {
   UGrid *grid = &tui->grid;
@@ -2327,6 +2330,9 @@ static size_t flush_buf_end(TUIData *tui, char *buf, size_t len)
   return offset;
 }
 
+/// Flushes the rendered buffer to the TTY.
+///
+/// @see tui_flush
 static void flush_buf(TUIData *tui)
 {
   uv_write_t req;
diff --git a/test/functional/lua/watch_spec.lua b/test/functional/lua/watch_spec.lua
index 106d40fe0e..044d707499 100644
--- a/test/functional/lua/watch_spec.lua
+++ b/test/functional/lua/watch_spec.lua
@@ -99,7 +99,10 @@ describe('vim._watch', function()
 
   describe('poll', function()
     it('detects file changes', function()
-      skip(is_os('bsd'), 'bsd only reports rename on folders if file inside change')
+      skip(
+        is_os('bsd'),
+        'kqueue only reports events on watched folder itself, not contained files #26110'
+      )
       local root_dir = vim.uv.fs_mkdtemp(vim.fs.dirname(helpers.tmpname()) .. '/nvim_XXXXXXXXXX')
 
       local result = exec_lua(
diff --git a/test/functional/plugin/lsp_spec.lua b/test/functional/plugin/lsp_spec.lua
index 252931eccb..b602143443 100644
--- a/test/functional/plugin/lsp_spec.lua
+++ b/test/functional/plugin/lsp_spec.lua
@@ -4261,7 +4261,10 @@ describe('LSP', function()
 
   describe('vim.lsp._watchfiles', function()
     it('sends notifications when files change', function()
-      skip(is_os('bsd'), 'bsd only reports rename on folders if file inside change')
+      skip(
+        is_os('bsd'),
+        'kqueue only reports events on watched folder itself, not contained files #26110'
+      )
       local root_dir = tmpname()
       os.remove(root_dir)
       mkdir(root_dir)