docs #22363

Co-authored by: zeertzjq <zeertzjq@outlook.com>
Co-authored by: Steven Todd McIntyre II <114119064+stmii@users.noreply.github.com>
Co-authored by: nobe4 <nobe4@users.noreply.github.com>

- docs: mention --luadev-mod to run with lua runtime files
  When changing a lua file in the ./runtime folder, a new contributor
  might expect changes to be applied to the built Neovim binary.

18 files changed, 175 insertions, 130 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 4c8387fbd2..91badd4c58 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -33,7 +33,7 @@ Reporting problems
 Developer guidelines
 --------------------
 
-- Read [:help dev](https://neovim.io/doc/user/develop.html#dev) if you are working on Nvim core.
+- Read [:help dev](https://neovim.io/doc/user/develop.html#dev) and [:help dev-doc][dev-doc-guide] if you are working on Nvim core.
 - Read [:help dev-ui](https://neovim.io/doc/user/develop.html#dev-ui) if you are developing a UI.
 - Read [:help dev-api-client](https://neovim.io/doc/user/develop.html#dev-api-client) if you are developing an API client.
 - Install `ninja` for faster builds of Nvim.
@@ -264,40 +264,52 @@ For managing includes in C files, use [include-what-you-use].
 
 See [#549][549] for more details.
 
+### Lua runtime files
+
+Most of the Lua core [`runtime/`](./runtime) modules are precompiled to
+bytecode, so changes to those files won't get used unless you rebuild Nvim or
+by passing `--luamod-dev` and `$VIMRUNTIME`. For example, try adding a function
+to `runtime/lua/vim/_editor.lua` then:
+
+    VIMRUNTIME=./runtime ./build/bin/nvim --luamod-dev
+
 Documenting
 -----------
 
-Many parts of the `:help` documentation are autogenerated from C or Lua docstrings using the `./scripts/gen_vimdoc.py` script.
-You can filter the regeneration based on the target (api, lua, or lsp), or the file you changed, that need a doc refresh using `./scripts/gen_vimdoc.py -t <target>`.
+Read [:help dev-doc][dev-doc-guide] to understand the expected documentation style and conventions.
 
-## Lua docstrings
+### Generating :help
 
-Lua documentation uses a subset of [EmmyLua] annotations. A rough outline of a function documentation is
+Many `:help` docs are autogenerated from (C or Lua) docstrings by the `./scripts/gen_vimdoc.py` script.
+For convenience you can filter the regeneration by target (api, lua, lsp) using the `-t` option, for example:
 
-```lua
---- {Brief}
----
---- {Long explanation}
----
----@param arg1 type {description}
----@param arg2 type {description}
-{...}
----
----@return type {description}
-```
+    ./scripts/gen_vimdoc.py -t lua
 
-If possible, always add type information (`table`, `string`, `number`, ...). Multiple valid types are separated by a bar (`string|table`). Indicate optional parameters via `type|nil`.
+### Lua docstrings
 
-If a function in your Lua module should not be documented (e.g. internal function or local function), you should set the doc comment to:
-
-```
----@private
-```
+Lua documentation uses a subset of [EmmyLua] annotations. See [:help dev-doc-lua][dev-doc-lua].
 
-Mark functions that are deprecated as
-```
----@deprecated
-```
+- The template for function documentation is:
+  ```lua
+  --- {Brief}
+  ---
+  --- {Long explanation}
+  ---
+  ---@param arg1 type {description}
+  ---@param arg2 type {description}
+  --- ...
+  ---
+  ---@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:
+  ```
+  ---@private
+  ```
+- Mark deprecated functions with:
+  ```
+  ---@deprecated
+  ```
 
 Reviewing
 ---------
@@ -326,6 +338,8 @@ as context, use the `-W` argument as well.
 [Merge a Vim patch]: https://github.com/neovim/neovim/wiki/Merging-patches-from-upstream-Vim
 [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
 [EmmyLua]: https://github.com/sumneko/lua-language-server/wiki/Annotations
 [gcc-warnings]: https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html
 [gh]: https://cli.github.com/
diff --git a/MAINTAIN.md b/MAINTAIN.md
index 2ba764851b..c0f330018b 100644
--- a/MAINTAIN.md
+++ b/MAINTAIN.md
@@ -93,6 +93,8 @@ These dependencies are "vendored" (inlined), we must update the sources manually
 * `runtime/lua/vim/inspect.lua`: [inspect.lua](https://github.com/kikito/inspect.lua)
 * `src/nvim/tui/terminfo_defs.h`: terminfo definitions
     * Run `scripts/update_terminfo.sh` to update these definitions.
+* `runtime/lua/vim/lsp/types/protocol.lua`: LSP specification
+    * Run `scripts/lsp_types.lua` to update.
 * `src/bit.c`: only for PUC lua: port of `require'bit'` from luajit https://bitop.luajit.org/
 * [treesitter parsers](https://github.com/neovim/neovim/blob/fcc24e43e0b5f9d801a01ff2b8f78ce8c16dd551/cmake.deps/CMakeLists.txt#L197-L210)
 
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 1732c24f2f..fe3f763648 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -2819,6 +2819,9 @@ nvim_win_get_cursor({window})                          *nvim_win_get_cursor()*
     Return: ~
         (row, col) tuple
 
+    See also: ~
+      • |getcurpos()|
+
 nvim_win_get_height({window})                          *nvim_win_get_height()*
     Gets the window height
 
diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index 938523b6ee..d170240ef7 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -4542,6 +4542,8 @@ 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.
+
 		Spawns {cmd} as a job.
 		If {cmd} is a List it runs directly (no 'shell').
 		If {cmd} is a String it runs in the 'shell', like this: >
@@ -4597,11 +4599,9 @@ jobstart({cmd} [, {opts}])				*jobstart()*
 			      stdout data.
 		  |on_stderr|:  (function) Callback invoked when the job emits
 			      stderr data.
-		  overlapped: (boolean) Set FILE_FLAG_OVERLAPPED for the
-			      standard input/output passed to the child process.
-			      Normally you do not need to set this.
-			      (Only available on MS-Windows, On other
-			      platforms, this option is silently ignored.)
+		  overlapped: (boolean) Sets FILE_FLAG_OVERLAPPED for the
+			      stdio passed to the child process. Only on
+			      MS-Windows; ignored on other platforms.
 		  pty:	      (boolean) Connect the job to a new pseudo
 			      terminal, and its streams to the master file
 			      descriptor. `on_stdout` receives all output,
@@ -8665,6 +8665,8 @@ synstack({lnum}, {col})					*synstack()*
 		valid positions.
 
 system({cmd} [, {input}])				*system()* *E677*
+		Note: Prefer |vim.system()| in Lua.
+
 		Gets the output of {cmd} as a |string| (|systemlist()| returns
 		a |List|) and sets |v:shell_error| to the error code.
 		{cmd} is treated as in |jobstart()|:
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 73888a32cc..29a0470ded 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -163,27 +163,21 @@ OPTIONS
 - 'viewoptions'		Flags "unix", "slash" are ignored and always enabled.
 - *'viminfo'*		Deprecated alias to 'shada' option.
 - *'viminfofile'*	Deprecated alias to 'shadafile' option.
-- *'paste'* *'nopaste'*	This option is obsolete; |paste| is handled automatically.
+- *'paste'* *'nopaste'*	Just Paste It.™  The 'paste' option is obsolete:
+			|paste| is handled automatically when you paste text
+			using your terminal's or GUI's paste feature
+			(CTRL-SHIFT-v, CMD-v (macOS), middle-click, …).
 			Enables "paste mode":
-			  - mappings in Insert mode and Command-line mode are
-			    disabled
-			  - abbreviations are disabled
-			  - 'autoindent' is reset
-			  - 'expandtab' is reset
-			  - 'formatoptions' is used like it is empty
-			  - 'revins' is reset
-			  - 'ruler' is reset
-			  - 'showmatch' is reset
-			  - 'smartindent' is reset
-			  - 'smarttab' is reset
-			  - 'softtabstop' is set to 0
-			  - 'textwidth' is set to 0
-			  - 'wrapmargin' is set to 0
-			These options keep their value, but their effect is
-			disabled:
-			  - 'cindent'
-			  - 'indentexpr'
-			  - 'lisp'
+			  - Disables mappings in Insert, Cmdline mode.
+			  - Disables abbreviations.
+			  - Resets 'autoindent' 'expandtab' 'revins' 'ruler'
+			    'showmatch' 'smartindent' 'smarttab' 'softtabstop'
+			    'textwidth' 'wrapmargin'.
+			  - Treats 'formatoptions' as empty.
+			  - Disables the effect of these options:
+			    - 'cindent'
+			    - 'indentexpr'
+			    - 'lisp'
 
 UI EXTENSIONS
 - *ui-wildmenu*		Use |ui-cmdline| with |ui-popupmenu| instead. Enabled
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index b090fd4f09..891b068051 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -130,10 +130,14 @@ DOCUMENTATION						*dev-doc*
   (docstrings, user manual, website materials, newsletters, …). Don't mince
   words. Personality and flavor, used sparingly, are welcome--but in general,
   optimize for the reader's time and energy: be "precise yet concise".
-    - See https://developers.google.com/style/tone
     - Prefer the active voice: "Foo does X", not "X is done by Foo".
-- Start function docstrings with present tense ("Gets"), not imperative
-  ("Get"). This tends to reduce ambiguity and improve clarity. >
+    - "The words you choose are an essential part of the user experience."
+      https://developer.apple.com/design/human-interface-guidelines/foundations/writing/
+    - "...without being overly colloquial or frivolous."
+      https://developers.google.com/style/tone
+- Write docstrings (as opposed to inline comments) with present tense ("Gets"),
+  not imperative ("Get"). This tends to reduce ambiguity and improve clarity
+  by describing "What" instead of "How". >
     GOOD:
     /// Gets a highlight definition.
     BAD:
@@ -272,6 +276,12 @@ See also |dev-naming|.
   - mimic the pairs() or ipairs() interface if the function is intended to be
     used in a "for" loop.
 
+Interface conventions ~
+
+- When accepting a buffer id, etc., 0 means "current buffer", nil means "all
+  buffers".  Likewise for window id, tabpage id, etc.
+  - Examples: |vim.lsp.codelens.clear()| |vim.diagnostic.enable()|
+
 
 API DESIGN GUIDELINES					*dev-api*
 
@@ -346,6 +356,7 @@ Use consistent names for {noun} (nouns) in API functions: buffer is called
 
 Do NOT use these deprecated nouns:
     - buffer
+    - callback      Use on_foo instead
     - command
     - window
 
diff --git a/runtime/doc/editing.txt b/runtime/doc/editing.txt
index c774d1ad38..2e0f73a597 100644
--- a/runtime/doc/editing.txt
+++ b/runtime/doc/editing.txt
@@ -1677,9 +1677,9 @@ mark a file as trusted or untrusted using the |:trust| command or the
 :trust [++deny] [++remove] [file]
 
 			Manage trusted files. Without ++ options, :trust marks
-			[file] (or current buffer if no [file]) as trusted,
-			keyed on a hash of its contents. The trust list is
-			stored on disk, Nvim will re-use it after restarting.
+			the current buffer as trusted, keyed on a hash of its
+			contents. The trust list is stored on disk, Nvim will
+			re-use it after restarting.
 
 			[++deny] marks [file] (or current buffer if no [file]) as
 			untrusted: it will never be executed, 'exrc' will
diff --git a/runtime/doc/insert.txt b/runtime/doc/insert.txt
index de1b850a3f..a1e0675b36 100644
--- a/runtime/doc/insert.txt
+++ b/runtime/doc/insert.txt
@@ -1081,6 +1081,26 @@ Stop completion						*compl-stop*
 CTRL-X CTRL-Z		Stop completion without changing the text.
 
 
+AUTO-COMPLETION						*compl-autocomplete*
+
+To get basic "autocompletion" without installing a plugin, try this script: >lua
+
+  local triggers = {"."}
+  vim.api.nvim_create_autocmd("InsertCharPre", {
+    buffer = vim.api.nvim_get_current_buf(),
+    callback = function()
+      if vim.fn.pumvisible() == 1 then
+        return
+      end
+      local char = vim.v.char
+      if vim.tbl_contains(triggers, char) then
+        local key = vim.keycode("<C-x><C-n>")
+        vim.api.nvim_feedkeys(key, "m", false)
+      end
+    end
+  })
+<
+
 FUNCTIONS FOR FINDING COMPLETIONS			*complete-functions*
 
 This applies to 'completefunc', 'thesaurusfunc' and 'omnifunc'.
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index c4322e9c24..4f2c457107 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -46,38 +46,40 @@ Follow these steps to get LSP features:
      See |lsp-config|.
 
                                                         *lsp-config*
-
-Starting a LSP client will automatically report diagnostics via
-|vim.diagnostic|. Read |vim.diagnostic.config()| to learn how to customize the
-display.
-
-It also sets some buffer options if the language server supports the
-functionality and if the options are otherwise empty or have the default
-values set by Nvim runtime files (e.g. a ftplugin). In the latter case,
-the default values are not restored when the LSP client is detached from
-the buffer.
-
-- 'omnifunc' is set to |vim.lsp.omnifunc()|. This allows to trigger completion
-  using |i_CTRL-X_CTRL-O|
+                                                        *lsp-defaults*
+When the LSP client starts it enables diagnostics |vim.diagnostic| (see
+|vim.diagnostic.config()| to customize). It also sets various default options,
+listed below, if (1) the language server supports the functionality and (2)
+the options are empty or were set by the builtin runtime (ftplugin) files. The
+options are not restored when the LSP client is stopped or detached.
+
+- 'omnifunc' is set to |vim.lsp.omnifunc()|, use |i_CTRL-X_CTRL-O| to trigger
+  completion.
 - 'tagfunc' is set to |vim.lsp.tagfunc()|. This enables features like
   go-to-definition, |:tjump|, and keymaps like |CTRL-]|, |CTRL-W_]|,
   |CTRL-W_}| to utilize the language server.
-- 'formatexpr' is set to |vim.lsp.formatexpr()| if both 'formatprg' and
-  'formatexpr' are empty. This allows to format lines via |gq| if the language
-  server supports it.
+- 'formatexpr' is set to |vim.lsp.formatexpr()|, so you can format lines via
+  |gq| if the language server supports it.
+  - To opt out of this use |gw| instead of gq, or set 'formatexpr' on LspAttach.
 
-To use other LSP features like hover, rename, etc. you can setup some
-additional keymaps. It's recommended to setup them in a |LspAttach| autocmd to
-ensure they're only active if there is a LSP client running. An example:
->lua
+                                                        *lsp-defaults-disable*
+To override the above defaults, set or unset the options on |LspAttach|: >lua
+    vim.api.nvim_create_autocmd('LspAttach', {
+      callback = function(ev)
+        vim.bo[ev.buf].formatexpr = nil
+        vim.bo[ev.buf].omnifunc = nil
+      end,
+    })
+
+To use other LSP features like hover, rename, etc. you can set other keymaps
+on |LspAttach|. Example: >lua
     vim.api.nvim_create_autocmd('LspAttach', {
       callback = function(args)
         vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf })
       end,
     })
 
-<
-The most used functions are:
+The most common functions are:
 
 - |vim.lsp.buf.hover()|
 - |vim.lsp.buf.format()|
@@ -138,19 +140,6 @@ FAQ                                                     *lsp-faq*
      " (async = false is the default for format)
      autocmd BufWritePre *.rs lua vim.lsp.buf.format({ async = false })
 <
-- Q: How can I disable LSP formatting when using the |gq| command?
-  A: To use the default internal formatting method and bypass the LSP client's
-  'formatexpr', use |gw| instead.
-  Alternatively you can completely disable LSP formatting with gq by
-  unsetting 'formatexpr':
-
->lua
-    vim.api.nvim_create_autocmd('LspAttach', {
-        callback = function(args)
-            vim.bo[args.buf].formatexpr = nil
-        end,
-    })
-<
                                                            *lsp-vs-treesitter*
 - Q: How do LSP and Treesitter compare?
   A: LSP requires a client and language server. The language server uses
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 737aa91e97..a4890898a3 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2970,8 +2970,9 @@ range({spec})                                            *vim.version.range()*
 Lua module: iter                                                    *lua-iter*
 
 
-The *vim.iter* module provides a generic "iterator" interface over tables
-and iterator functions.
+The *vim.iter* 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
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index f2a878078d..cd3b1bd45e 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -44,9 +44,13 @@ The following changes may require adaptations in user config or plugins.
 • Renamed `vim.treesitter.playground` to `vim.treesitter.dev`.
 
 ==============================================================================
-ADDED FEATURES                                                     *news-added*
+NEW FEATURES                                                    *news-features*
 
-The following new APIs or features were added.
+The following new APIs and features were added.
+
+• Performance:
+  • 'diffopt' "linematch" scoring algorithm now favours larger and less groups
+    https://github.com/neovim/neovim/pull/23611
 
 • Added |vim.lsp.status()| to consume the last progress messages as a string.
 
diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
index c64c450aa1..1391ef2808 100644
--- a/runtime/doc/ui.txt
+++ b/runtime/doc/ui.txt
@@ -199,7 +199,7 @@ the editor.
 	The following keys are deprecated:
 
 	`hl_id`:	Use `attr_id` instead.
-	`hl_lm`:	Use `attr_id_lm` instead.
+	`id_lm`:	Use `attr_id_lm` instead.
 
 ["option_set", name, value] ~
 	UI-related option changed, where `name` is one of:
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index ab1b2056a2..ff3e19689b 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -15,6 +15,9 @@ centralized reference of the differences.
 ==============================================================================
 Configuration						    *nvim-config*
 
+User configuration and data files are found in standard |base-directories|
+(see also |$NVIM_APPNAME|).  Note in particular:
+
 - Use `$XDG_CONFIG_HOME/nvim/init.vim` instead of `.vimrc` for your |config|.
 - Use `$XDG_CONFIG_HOME/nvim` instead of `.vim` to store configuration files.
 - Use `$XDG_STATE_HOME/nvim/shada/main.shada` instead of `.viminfo` for persistent
@@ -29,7 +32,7 @@ Defaults					            *nvim-defaults*
   ":syntax off" to |init.vim|.
 
 - 'autoindent' is enabled
-- 'autoread' is enabled
+- 'autoread' is enabled (works in all UIs, including terminal)
 - 'background' defaults to "dark" (unless set automatically by the terminal/UI)
 - 'backspace' defaults to "indent,eol,start"
 - 'backupdir' defaults to .,~/.local/state/nvim/backup// (|xdg|), auto-created
@@ -195,7 +198,7 @@ server.
 External plugins run in separate processes. |remote-plugin| This improves
 stability and allows those plugins to work without blocking the editor. Even
 "legacy" Python and Ruby plugins which use the old Vim interfaces (|if_pyth|,
-|if_ruby|) run out-of-process.
+|if_ruby|) run out-of-process, so they cannot crash Nvim.
 
 Platform and I/O facilities are built upon libuv. Nvim benefits from libuv
 features and bug fixes, and other projects benefit from improvements to libuv
@@ -273,6 +276,7 @@ Normal commands:
   |Q| replays the last recorded macro instead of switching to Ex mode (|gQ|).
 
 Options:
+  'autoread'    works in the terminal (if it supports "focus" events)
   'cpoptions'   flags: |cpo-_|
   'diffopt'     "linematch" feature
   'exrc'        searches for ".nvim.lua", ".nvimrc", or ".exrc" files. The
@@ -293,7 +297,6 @@ Options:
   'shortmess'   "F" flag does not affect output from autocommands
   'signcolumn'  supports up to 9 dynamic/fixed columns
   'statuscolumn' full control of columns using 'statusline' format
-  'statusline'  supports unlimited alignment sections
   'tabline'     %@Func@foo%X can call any function on mouse-click
   'ttimeout', 'ttimeoutlen' behavior was simplified
   'winblend'    pseudo-transparency in floating windows |api-floatwin|
@@ -382,9 +385,9 @@ These Nvim features were later integrated into Vim.
 - 'statusline' supports unlimited alignment sections
 
 ==============================================================================
-Changed features					 *nvim-changed*
+Other changes						 *nvim-changed*
 
-This section lists various low-level details about other behavior changes.
+This section documents various low-level behavior changes.
 
 |mkdir()| behaviour changed:
 1. Assuming /tmp/foo does not exist and /tmp can be written to
@@ -399,21 +402,21 @@ This section lists various low-level details about other behavior changes.
    structures.
 2. |string()| fails immediately on nested containers, not when recursion limit
    was exceeded.
-2. When |:echo| encounters duplicate containers like >vim
+3. When |:echo| encounters duplicate containers like >vim
 
        let l = []
        echo [l, l]
 <
    it does not use "[...]" (was: "[[], [...]]", now: "[[], []]"). "..." is
    only used for recursive containers.
-3. |:echo| printing nested containers adds "@level" after "..." designating
+4. |:echo| printing nested containers adds "@level" after "..." designating
    the level at which recursive container was printed: |:echo-self-refer|.
    Same thing applies to |string()| (though it uses construct like
    "{E724@level}"), but this is not reliable because |string()| continues to
    error out.
-4. Stringifyed infinite and NaN values now use |str2float()| and can be evaled
+5. Stringifyed infinite and NaN values now use |str2float()| and can be evaled
    back.
-5. (internal) Trying to print or stringify VAR_UNKNOWN in Vim results in 
+6. (internal) Trying to print or stringify VAR_UNKNOWN in Vim results in 
    nothing, E908, in Nvim it is internal error.
 
 |json_decode()| behaviour changed:
@@ -634,7 +637,10 @@ Options:
   'highlight' (Names of builtin |highlight-groups| cannot be changed.)
   *'hkmap'* *'hk'* use `set keymap=hebrew` instead.
   *'hkmapp'* *'hkp'* use `set keymap=hebrewp` instead.
-  *'pastetoggle'* *'pt'*
+
+  *'pastetoggle'* *'pt'* Just Paste It.™ |paste| is handled automatically when
+  you paste text using your terminal's or GUI's paste feature (CTRL-SHIFT-v,
+  CMD-v (macOS), middle-click, …).
 
   *'imactivatefunc'* *'imaf'*
   *'imactivatekey'* *'imak'*
@@ -705,6 +711,11 @@ Options:
 Performance:
   Folds are not updated during insert-mode.
 
+Plugins:
+
+- logiPat
+- rrhelper
+
 Providers:
 
 - *if_lua* : Nvim |Lua| API is not compatible with Vim's "if_lua".
@@ -762,7 +773,8 @@ TUI:
 
 Cscope:
                                                                       *cscope*
-  Cscope support has been removed in favour of plugin-based solutions.
+  Cscope support was removed in favour of plugin-based solutions such as:
+  https://github.com/dhananjaylatkar/cscope_maps.nvim
 
 Hardcopy:
                                                                      *hardcopy*
diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua
index 204d22b9be..9c7bd13164 100644
--- a/runtime/lua/vim/iter.lua
+++ b/runtime/lua/vim/iter.lua
@@ -1,7 +1,8 @@
 ---@defgroup lua-iter
 ---
---- The \*vim.iter\* module provides a generic "iterator" interface over tables
---- and iterator functions.
+--- @brief The \*vim.iter\* 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
diff --git a/src/man/nvim.1 b/src/man/nvim.1
index c32bdeadc6..b846ed4ba6 100644
--- a/src/man/nvim.1
+++ b/src/man/nvim.1
@@ -193,7 +193,7 @@ is
 do not read or write a ShaDa file.
 .Ic ":help shada"
 .It Fl -noplugin
-Skip loading plugins.
+Skip loading plugins (by setting the 'noloadplugins' option).
 Implied by
 .Cm -u NONE .
 .It Fl -clean
diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c
index c021fec220..97bf0f377a 100644
--- a/src/nvim/api/window.c
+++ b/src/nvim/api/window.c
@@ -57,6 +57,8 @@ void nvim_win_set_buf(Window window, Buffer buffer, Error *err)
 /// (different windows showing the same buffer have independent cursor
 /// positions). |api-indexing|
 ///
+/// @see |getcurpos()|
+///
 /// @param window   Window handle, or 0 for current window
 /// @param[out] err Error details, if any
 /// @return (row, col) tuple
diff --git a/src/nvim/main.c b/src/nvim/main.c
index 6ab7391b05..83e56c3066 100644
--- a/src/nvim/main.c
+++ b/src/nvim/main.c
@@ -2185,43 +2185,33 @@ static void usage(void)
   signal_stop();              // kill us with CTRL-C here, if you like
 
   os_msg(_("Usage:\n"));
-  os_msg(_("  nvim [options] [file ...]      Edit file(s)\n"));
-  os_msg(_("  nvim [options] -t <tag>        Edit file where tag is defined\n"));
-  os_msg(_("  nvim [options] -q [errorfile]  Edit file with first error\n"));
+  os_msg(_("  nvim [options] [file ...]\n"));
   os_msg(_("\nOptions:\n"));
-  os_msg(_("  --                    Only file names after this\n"));
-  os_msg(_("  +                     Start at end of file\n"));
   os_msg(_("  --cmd <cmd>           Execute <cmd> before any config\n"));
   os_msg(_("  +<cmd>, -c <cmd>      Execute <cmd> after config and first file\n"));
   os_msg(_("  -l <script> [args...] Execute Lua <script> (with optional args)\n"));
+  os_msg(_("  -S <session>          Source <session> after loading the first file\n"));
+  os_msg(_("  -s <scriptin>         Read Normal mode commands from <scriptin>\n"));
+  os_msg(_("  -u <config>           Use this config file\n"));
   os_msg("\n");
-  os_msg(_("  -b                    Binary mode\n"));
   os_msg(_("  -d                    Diff mode\n"));
-  os_msg(_("  -e, -E                Ex mode\n"));
   os_msg(_("  -es, -Es              Silent (batch) mode\n"));
   os_msg(_("  -h, --help            Print this help message\n"));
   os_msg(_("  -i <shada>            Use this shada file\n"));
-  os_msg(_("  -m                    Modifications (writing files) not allowed\n"));
-  os_msg(_("  -M                    Modifications in text not allowed\n"));
   os_msg(_("  -n                    No swap file, use memory only\n"));
   os_msg(_("  -o[N]                 Open N windows (default: one per file)\n"));
   os_msg(_("  -O[N]                 Open N vertical windows (default: one per file)\n"));
   os_msg(_("  -p[N]                 Open N tab pages (default: one per file)\n"));
-  os_msg(_("  -r, -L                List swap files\n"));
-  os_msg(_("  -r <file>             Recover edit state for this file\n"));
-  os_msg(_("  -R                    Read-only mode\n"));
-  os_msg(_("  -S <session>          Source <session> after loading the first file\n"));
-  os_msg(_("  -s <scriptin>         Read Normal mode commands from <scriptin>\n"));
-  os_msg(_("  -u <config>           Use this config file\n"));
+  os_msg(_("  -R                    Read-only (view) mode\n"));
   os_msg(_("  -v, --version         Print version information\n"));
   os_msg(_("  -V[N][file]           Verbose [level][file]\n"));
   os_msg("\n");
+  os_msg(_("  --                    Only file names after this\n"));
   os_msg(_("  --api-info            Write msgpack-encoded API metadata to stdout\n"));
   os_msg(_("  --clean               \"Factory defaults\" (skip user config and plugins, shada)\n"));
   os_msg(_("  --embed               Use stdin/stdout as a msgpack-rpc channel\n"));
   os_msg(_("  --headless            Don't start a user interface\n"));
   os_msg(_("  --listen <address>    Serve RPC API from this address\n"));
-  os_msg(_("  --noplugin            Don't load plugins\n"));
   os_msg(_("  --remote[-subcommand] Execute commands remotely on a server\n"));
   os_msg(_("  --server <address>    Specify RPC server to send commands to\n"));
   os_msg(_("  --startuptime <file>  Write startup timing messages to <file>\n"));
diff --git a/test/old/testdir/test_startup.vim b/test/old/testdir/test_startup.vim
index da467ea23f..d2ffbd0e2f 100644
--- a/test/old/testdir/test_startup.vim
+++ b/test/old/testdir/test_startup.vim
@@ -125,15 +125,15 @@ func Test_help_arg()
     " check if  couple of lines are there
     let found = []
     for line in lines
-      if line =~ '-R.*Read-only mode'
-        call add(found, 'Readonly mode')
+      if line =~ '-l.*Execute Lua'
+        call add(found, 'Execute Lua')
       endif
       " Watch out for a second --version line in the Gnome version.
       if line =~ '--version.*Print version information'
         call add(found, "--version")
       endif
     endfor
-    call assert_equal(['Readonly mode', '--version'], found)
+    call assert_equal(['Execute Lua', '--version'], found)
   endif
   call delete('Xtestout')
 endfunc