docs: lsp, misc

- Problem: It's not clear for new plugin developers that `:help` uses
  a help-tags file for searching the docs, generated by `:helptags`.
  - Solution: Hint to the |:helptags| docs for regenerating the tags
    file for their freshly written documentation.

Co-authored-by: Yochem van Rosmalen <[email protected]>

Author: justinmk

runtime/doc/api-ui-events.txt

@@ -826,7 +826,8 @@ message window. Cmdline state is emitted as |ui-cmdline| events, which the UI
 must handle.
 
 ["msg_show", kind, content, replace_last, history, append, msg_id] ~
-	Display a message to the user.
+	Display a message to the user. Update (replace) any existing message
+	matching `msg_id`.
 
 	kind
 	    Name indicating the message kind:

runtime/doc/api.txt

@@ -1385,9 +1385,9 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
     debugging and orchestration. (Note: Something is better than nothing!
     Fields are optional, but at least set `name`.)
 
-    Can be called more than once; the caller should merge old info if
-    appropriate. Example: library first identifies the channel, then a plugin
-    using that library later identifies itself.
+    Can be called more than once; caller should merge old info if appropriate.
+    Example: a library first identifies the channel, then a plugin using that
+    library later identifies itself.
 
     Attributes: ~
         |RPC| only
@@ -3324,8 +3324,7 @@ nvim_set_decoration_provider({ns_id}, {opts})
                  • on_win: called when starting to redraw a specific window. >
                     ["win", winid, bufnr, toprow, botrow]
 <
-                 • on_line: called for each buffer line being redrawn. (The
-                   interaction with fold lines is subject to change) >
+                 • on_line: (deprecated, use on_range instead) >
                     ["line", winid, bufnr, row]
 <
                  • on_range: called for each buffer range being redrawn. Range

runtime/doc/change.txt

@@ -1153,23 +1153,23 @@ first word).  You can use the |']| or |`]| command after the put command to
 move the cursor to the end of the inserted text, or use |'[| or |`[| to move
 the cursor to the start.
 
-						*put-Visual-mode* *v_p* *v_P*
+							     *put-Visual-mode*
 When using a put command like |p| or |P| in Visual mode, Vim will try to
-replace the selected text with the contents of the register.  Whether this
-works well depends on the type of selection and the type of the text in the
-register.  With blockwise selection it also depends on the size of the block
-and whether the corners are on an existing character.  (Implementation detail:
-it actually works by first putting the register after the selection and then
-deleting the selection.)
-With |p| the previously selected text is put in the unnamed register (and
-possibly the selection and/or clipboard).  This is useful if you want to put
-that text somewhere else.  But you cannot repeat the same change.
-With |P| the unnamed register is not changed (and neither the selection or
-clipboard), you can repeat the same change. But the deleted text cannot be
-used.  If you do need it you can use |p| with another register.  E.g., yank
-the text to copy, Visually select the text to replace and use "0p .  You can
-repeat this as many times as you like, and the unnamed register will be
-changed each time.
+replace the selected text with the contents of the register.  How this
+works depends on the type of selection and the text. With blockwise selection
+it also depends on the size of the block and whether the corners are on an
+existing character.  (Implementation detail: it actually works by first
+putting the register after the selection and then deleting the selection.)
+									 *v_p*
+|p| in Visual mode puts text and sets the default register (unnamed,
+selection, or clipboard) to the previously-selected text.  Useful if you want
+to put that text somewhere else.  But you cannot repeat the same change.
+									 *v_P*
+|P| in Visual mode puts text without setting the default register. You can
+repeat the change, but the deleted text cannot be used.  If you do need it you
+can use |p| with another register.  E.g., yank the text to copy, Visually
+select the text to replace and use "0p .  You can repeat this as many times as
+you like, and the unnamed register will be changed each time.
 							*blockwise-put*
 When a register contains text from one line (characterwise), using a
 blockwise Visual selection, putting that register will paste that text

runtime/doc/develop.txt

@@ -451,6 +451,8 @@ Use existing common {verb} names (actions) if possible:
                     a handler. |dev-name-events|
     - open:         Opens something (a buffer, window, …)
     - parse:        Parses something into a structured form
+    - request:      Calls a remote (network, RPC) operation.
+    - send:         Writes data or a message to a channel.
     - set:          Sets a thing (or group of things)
     - start:        Spin up a long-lived process. Prefer "enable" except when
                     "start" is obviously more appropriate.
@@ -461,7 +463,7 @@ Do NOT use these deprecated verbs:
     - contains:     Prefer "has".
     - disable:      Prefer `enable(enable: boolean)`.
     - exit:         Prefer "cancel" (or "stop" if appropriate).
-    - is_disabled:  Prefer `is_enabled()`.
+    - is_disabled:  Prefer `!is_enabled()`.
     - list:         Redundant with "get"
     - notify:       Redundant with "print", "echo"
     - show:         Redundant with "print", "echo"

runtime/doc/insert.txt

@@ -104,14 +104,13 @@ CTRL-R {register}				*i_CTRL-R*
 		Insert the contents of a register. Between typing CTRL-R and
 		the second character, '"' will be displayed to indicate that
 		you are expected to enter the name of a register. When used
-		with When used with named or clipboard registers
-		(A-Z,a-z,0-9,+) text is inserted literally like pasting with
-		"p". For other registers, the text is inserted as if you typed
-		it, but mappings and abbreviations are not used.  If you have
-		options like 'textwidth', 'formatoptions', or 'autoindent'
-		set, this will influence what will be inserted. This is
-		different from what happens with the "p" command and pasting
-		with the mouse.
+		with named or clipboard registers (A-Z,a-z,0-9,+) text is
+		inserted literally like pasting with "p". For other registers,
+		the text is inserted as if you typed it, but mappings and
+		abbreviations are not used.  If you have options like
+		'textwidth', 'formatoptions', or 'autoindent' set, this will
+		influence what will be inserted. This is different from what
+		happens with the "p" command and pasting with the mouse.
 		Special registers:
 			'"'	the unnamed register, containing the text of
 				the last delete or yank

runtime/doc/lsp.txt

@@ -2229,6 +2229,37 @@ is_enabled({filter})                         *vim.lsp.inlay_hint.is_enabled()*
 ==============================================================================
 Lua module: vim.lsp.inline_completion                  *lsp-inline_completion*
 
+This module provides the LSP "inline completion" feature, for completing
+multiline text (e.g., whole methods) instead of just a word or line, which may
+result in "syntactically or semantically incorrect" code. Unlike regular
+completion, this is typically presented as overlay text instead of a menu of
+completion candidates.
+
+LSP spec:
+https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#textDocument_inlineCompletion
+
+To try it out, here is a quickstart example using Copilot:       *lsp-copilot*
+1. Install Copilot: >sh
+    npm install --global @github/copilot-language-server
+<
+2. Define a config, (or copy `lsp/copilot.lua` from
+   https://github.com/neovim/nvim-lspconfig): >lua
+    vim.lsp.config('copilot', {
+     cmd = { 'copilot-language-server', '--stdio', },
+     root_markers = { '.git' },
+   })
+<
+3. Activate the config: >lua
+    vim.lsp.enable('copilot')
+<
+4. Sign in to Copilot, or use the `:LspCopilotSignIn` command from
+   https://github.com/neovim/nvim-lspconfig
+5. Enable inline completion: >lua
+    vim.lsp.inline_completion.enable()
+<
+6. Set a keymap for `vim.lsp.inline_completion.get()` and invoke the keymap.
+
+
 *vim.lsp.inline_completion.Item*
 
     Fields: ~

runtime/doc/lua-guide.txt

@@ -10,9 +10,9 @@
 ==============================================================================
 Introduction                                                         *lua-guide*
 
-This guide introduces the basics of everyday usage of Lua to configure and
-operate Nvim. It assumes some familiarity with the (non-Lua) basics of Nvim
-(commands, options, mappings, autocommands), which are covered in the
+This guide introduces the basics of everyday Lua usage for configuring and
+controlling Nvim. It assumes some familiarity with the (non-Lua) basics of
+Nvim (commands, options, mappings, autocommands), which are covered in the
 |user-manual|.
 
 This is not a comprehensive encyclopedia of all available features. Think of

runtime/doc/lua-plugin.txt

@@ -10,7 +10,7 @@
 ==============================================================================
 Introduction                                                       *lua-plugin*
 
-This document provides guidance for developing Nvim (Lua) plugins:
+This document provides guidance for developing Nvim Lua plugins.
 
 See |lua-guide| for guidance on using Lua to configure and operate Nvim.
 See |luaref| and |lua-concepts| for details on the Lua programming language.
@@ -19,7 +19,7 @@ See |luaref| and |lua-concepts| for details on the Lua programming language.
 Creating your first plugin                                    *lua-plugin-new*
 
 Any Vimscript or Lua code file that lives in the right directory,
-automatically is a "plugin". There's no maniest or "registration" required.
+automatically is a "plugin". There's no manifest or "registration" step.
 
 You can try it right now:
 
@@ -35,7 +35,7 @@ You can try it right now:
 
 Besides `plugin/foo.lua`, which is always run at startup, you can define Lua
 modules in the `lua/` directory. Those modules aren't loaded until your
-`plugin/foo.lua`, the user, calls `require(…)`.
+`plugin/foo.lua`, or the user, calls `require(…)`.
 
 ==============================================================================
 Type safety                                            *lua-plugin-type-safety*
@@ -108,11 +108,11 @@ In your plugin:
 >lua
     vim.keymap.set('n', '<Plug>(SayHello)', function()
         print('Hello from normal mode')
-    end, { noremap = true })
+    end)
 
     vim.keymap.set('v', '<Plug>(SayHello)', function()
         print('Hello from visual mode')
-    end, { noremap = true })
+    end)
 <
 In the user's config:
 >lua
@@ -176,7 +176,9 @@ For example, instead of:
     local foo = require('foo')
     vim.api.nvim_create_user_command('MyCommand', function()
         foo.do_something()
-    end, { -- ... })
+    end, {
+      -- ...
+    })
 <
 which calls `require('foo')` as soon as the module is loaded, you can
 lazy-load it by moving the `require` into the command's implementation:
@@ -227,7 +229,7 @@ A plugin tailored to Rust development might have initialization in
     -- e.g. add a |<Plug>| mapping or create a command
     vim.keymap.set('n', '<Plug>(MyPluginBufferAction)', function()
         print('Hello')
-    end, { noremap = true, buffer = bufnr, })
+    end, { buffer = bufnr, })
 <
 ==============================================================================
 Configuration                                              *lua-plugin-config*
@@ -274,7 +276,7 @@ Versioning and releases                                *lua-plugin-versioning*
 Consider:
 
 - Use |vim.deprecate()| or a `---@deprecate` annotation when you need to
-  communicate a (future) breaking change or discourged practice.
+  communicate a (future) breaking change or discouraged practice.
 - Using SemVer https://semver.org/ tags and releases to properly communicate
   bug fixes, new features, and breaking changes.
 - Automating versioning and releases in CI.
@@ -299,7 +301,9 @@ VERSIONING TOOLS
 Documentation                                                 *lua-plugin-doc*
 
 Provide vimdoc (see |help-writing|), so that users can read your plugin's
-documentation in Nvim, by entering `:h {plugin}` in |command-mode|.
+documentation in Nvim, by entering `:h {plugin}` in |command-mode|. The
+help-tags (the right-aligned "search keywords" in the help documents) are
+regenerated using the |:helptags| command.
 
 DOCUMENTATION TOOLS
 

runtime/doc/message.txt

@@ -848,25 +848,32 @@ prompt.
 ==============================================================================
 4. PROGRESS MESSAGE                                    *progress-message*
 
-Nvim can emit progress-message, which are a special kind of |ui-messages|
-used to report the state of long-running tasks.
+Plugins and core Nvim features can emit "progress" |ui-messages| to report the
+state of long-running tasks.
 
-Progress messages are created or updated using |nvim_echo()| with `kind='progress'`
-and the related options. Each message has a unique `msg_id`. A subsequent
-message with the same `msg_id` replaces the older one.
+Create or update a progress-message by calling |nvim_echo()| with
+`kind='progress'`. Each message has a unique message-id, returned by
+`nvim_echo`. You can specify the id when calling `nvim_echo` to update an
+existing progress-message.
 
 Events: ~
     • msg_show |ui-messages| event is fired for ext-ui upon creation/update of a
     progress-message
     • Updating or creating a progress message also triggers the |Progress| autocommand.
 
-Example: >
-    local id = vim.api.nvim_echo({{'searching...'}}, true,
-          {kind='progress', status='running', percent=10, title="term"})
-    vim.api.nvim_echo({{'searching'}}, true,
-          {id=id, kind='progress', status='running', percent=50, title="term"})
-    vim.api.nvim_echo({{'done'}}, true,
-          {id=id, kind='progress', status='success', percent=100, title="term"})
+Example: >lua
+    local progress = {
+      kind = 'progress',
+      status = 'running',
+      percent = 10,
+      title = 'term',
+    }
+    progress.id = vim.api.nvim_echo({ { 'searching...' } }, true, progress)
+    progress.percent = 50
+    vim.api.nvim_echo({ { 'searching' } }, true, progress)
+    progress.status = 'success'
+    progress.percent = 100
+    vim.api.nvim_echo({ { 'done' } }, true, progress)
 <
 See also: |nvim_echo()| |ui-messages| |Progress|
 

runtime/doc/news.txt

@@ -68,8 +68,9 @@ DIAGNOSTICS
 
 EDITOR
 
-• |i_CTRL-R| inserts named registers (A-Z,a-z,0-9) literally like pasting instead of
-  as typed. To get the old behavior you can use `<C-R>=@x`.
+- |i_CTRL-R| inserts named/clipboard registers (A-Z,a-z,0-9+) literally, like
+  pasting instead of like user input. Improves performance, avoids broken
+  formatting. To get the old behavior you can use `<C-R>=@x`.
 
 EVENTS
 
@@ -203,9 +204,8 @@ EVENTS
 HIGHLIGHTS
 
 • |hl-DiffTextAdd| highlights added text within a changed line.
-• |hl-StderrMsg| |hl-StdoutMsg|
+• |hl-OkMsg| |hl-StderrMsg| |hl-StdoutMsg|
 • |hl-SnippetTabstopActive| highlights the currently active tabstop.
-• |hl-OkMsg| highlights success messages.
 
 LSP
 
@@ -244,6 +244,7 @@ LSP
 • |vim.lsp.buf.signature_help()| supports "noActiveParameterSupport".
 • Support for `textDocument/inlineCompletion` |lsp-inline_completion|
   https://microsoft.github.io/language-server-protocol/specifications/lsp/3.18/specification/#textDocument_inlineCompletion
+  See |lsp-inline_completion| for quickstart instructions.
 • Support for `textDocument/onTypeFormatting`: |lsp-on_type_formatting|
   https://microsoft.github.io/language-server-protocol/specification/#textDocument_onTypeFormatting
 
@@ -291,6 +292,7 @@ PERFORMANCE
   support for nested braces and follows LSP 3.17 specification with
   additional constraints for improved correctness and resistance to
   backtracking edge cases.
+- |i_CTRL-R| inserts named/clipboard registers literally, 10x speedup.
 
 PLUGINS