Merge #34558 docs

runtime/lua/vim/_meta/options.lua

@@ -619,10 +619,10 @@ vim.bo.bl = vim.bo.buflisted
 ---   help		help buffer (do not set this manually)
 ---   nofile	buffer is not related to a file, will not be written
 ---   nowrite	buffer will not be written
+---   prompt	buffer where only the last section can be edited, for
+--- 		use by plugins. `prompt-buffer`
 ---   quickfix	list of errors `:cwindow` or locations `:lwindow`
 ---   terminal	`terminal-emulator` buffer
----   prompt	buffer where only the last line can be edited, meant
---- 		to be used by a plugin, see `prompt-buffer`
 ---
 --- This option is used together with 'bufhidden' and 'swapfile' to
 --- specify special kinds of buffers.   See `special-buffers`.

runtime/lua/vim/_meta/vimfn.lua

@@ -2828,8 +2828,7 @@ function vim.fn.getchangelist(buf) end
 ---   Return zero otherwise.
 --- If {expr} is 1, only check if a character is available, it is
 ---   not consumed.  Return zero if no character available.
---- If you prefer always getting a string use |getcharstr()|, or
---- specify |FALSE| as "number" in {opts}.
+--- To always get a string, specify "number" as |FALSE| in {opts}.
 ---
 --- Without {expr} and when {expr} is 0 a whole character or
 --- special key is returned.  If it is a single character, the

runtime/lua/vim/keymap.lua

@@ -21,12 +21,12 @@ local keymap = {}
 ---
 --- ```lua
 --- -- Map "x" to a Lua function:
---- vim.keymap.set('n', 'x', function() print("real lua function") end)
+--- vim.keymap.set('n', 'x', function() print('real lua function') end)
 --- -- Map "<leader>x" to multiple modes for the current buffer:
 --- vim.keymap.set({'n', 'v'}, '<leader>x', vim.lsp.buf.references, { buffer = true })
 --- -- Map <Tab> to an expression (|:map-<expr>|):
 --- vim.keymap.set('i', '<Tab>', function()
----   return vim.fn.pumvisible() == 1 and "<C-n>" or "<Tab>"
+---   return vim.fn.pumvisible() == 1 and '<C-n>' or '<Tab>'
 --- end, { expr = true })
 --- -- Map "[%%" to a <Plug> mapping:
 --- vim.keymap.set('n', '[%%', '<Plug>(MatchitNormalMultiBackward)')

runtime/lua/vim/lsp.lua

@@ -1653,14 +1653,12 @@ function lsp.with(handler, override_config)
   end
 end
 
---- Registry (a table) for client-side handlers, for custom server-commands that are not in the LSP
---- specification.
+--- Map of client-defined handlers implementing custom (off-spec) commands which a server may
+--- invoke. Each key is a unique command name; each value is a function which is called when an LSP
+--- action (code action, code lenses, …) requests it by name.
 ---
---- If an LSP response contains a command which is not found in `vim.lsp.commands`, the command will
---- be executed via the LSP server using `workspace/executeCommand`.
----
---- Each key in the table is a unique command name, and each value is a function which is called
---- when an LSP action (code action, code lenses, …) triggers the command.
+--- If an LSP response requests a command not defined client-side, Nvim will forward it to the
+--- server as `workspace/executeCommand`.
 ---
 --- - Argument 1 is the `Command`:
 ---   ```
@@ -1686,7 +1684,7 @@ end
 --- end
 --- ```
 ---
---- @type table<string,function>
+--- @type table<string,fun(command: lsp.Command, ctx: table)>
 lsp.commands = setmetatable({}, {
   __newindex = function(tbl, key, value)
     assert(type(key) == 'string', 'The key for commands in `vim.lsp.commands` must be a string')

runtime/lua/vim/lsp/client.lua

@@ -63,10 +63,7 @@ local validate = vim.validate
 --- ```
 --- @field cmd_env? table
 ---
---- Client commands. Map of command names to user-defined functions. Commands passed to `start()`
---- take precedence over the global command registry. Each key must be a unique command name, and
---- the value is a function which is called if any LSP action (code action, code lenses, …) triggers
---- the command.
+--- Map of client-defined commands overriding the global |vim.lsp.commands|.
 --- @field commands? table<string,fun(command: lsp.Command, ctx: table)>
 ---
 --- Daemonize the server process so that it runs in a separate process group from Nvim.