docs: misc #40847

Co-authored-by: Barrett Ruth <br@barrettruth.com>
Co-authored-by: Nathan Zeng <nathan.j.zeng@gmail.com>

runtime/lua/vim/_core/editor.lua

@@ -1266,18 +1266,20 @@ end
 --- @class vim.keycode.chord
 --- @inlinedoc
 ---
---- Key without modifiers. Example: `<C-A>` has `key` `a`.
+--- Key without modifiers.
+--- Example: `<C-A>` has `key="a"`.
 --- @field key string
 ---
 --- Alternative spelling of `key`, or nil if There Is No Alternative (TINA).
---- Example: `key="<"` has `key_alt="lt"`.
+--- Example: `"<"` has `key_alt="lt"`.
 --- @field key_alt string?
 ---
 --- Full key-chord in canonical key-notation (as produced by |keytrans()|), including modifiers.
 --- Example: `<A-f>` has `keys="<M-f>"`.
 --- @field keys string
 ---
---- A list of single character modifiers of the key.
+--- List of key-chord modifiers.
+--- Example: `<C-S-f>` has `mod={ 'C', 'S' }`.
 --- @field mod ('M'|'T'|'C'|'S'|'2'|'3'|'4'|'D')[]
 
 --- Converts keys from [key-notation] to the internal encoding. Optionally returns structured
@@ -1302,7 +1304,7 @@ end
 ---
 --- @param keys string Keys in [key-notation].
 --- @param info boolean? Also return key-chord info.
---- @return string # Internal bytes representation of the given `keys`.
+--- @return string # Internal representation of the given `keys`.
 --- @return vim.keycode.chord[]? # List of parsed key-chords, each with fields:
 --- @see |nvim_replace_termcodes()|
 --- @see |keytrans()|

runtime/lua/vim/_meta.lua

@@ -11,53 +11,53 @@ vim.uv = ...
 --- EmmyLua reads the precise generics from `runtime/lua/vim/iter.lua`; LuaLS uses
 --- these broader shapes for downstream type-checking.
 --- @class vim.Iter
---- @field filter fun(self: vim.Iter, f: fun(...): boolean): vim.Iter
---- @field unique fun(self: vim.Iter, key?: fun(...): any): vim.Iter
---- @field flatten fun(self: vim.Iter, depth?: integer): vim.IterArray
---- @field map fun(self: vim.Iter, f: fun(...): ...): vim.Iter
---- @field each fun(self: vim.Iter, f: fun(...)): nil
---- @field totable fun(self: vim.Iter): table
---- @field join fun(self: vim.Iter, delim: string): string
---- @field fold fun(self: vim.Iter, init: any, f: fun(acc: any, ...): any): any
---- @field next fun(self: vim.Iter): any
---- @field rev fun(self: vim.Iter): vim.IterArray
---- @field peek fun(self: vim.Iter): any
---- @field find fun(self: vim.Iter, f: any): any
---- @field rfind fun(self: vim.Iter, f: any): any
---- @field take fun(self: vim.Iter, n: integer|fun(...): boolean): vim.Iter
---- @field pop fun(self: vim.Iter): any
---- @field rpeek fun(self: vim.Iter): any
---- @field skip fun(self: vim.Iter, n: integer|fun(...): boolean): vim.Iter
---- @field rskip fun(self: vim.Iter, n: integer): vim.IterArray
---- @field nth fun(self: vim.Iter, n: integer): any
---- @field slice fun(self: vim.Iter, first: integer, last: integer): vim.IterArray
---- @field any fun(self: vim.Iter, pred: fun(...): boolean): boolean
 --- @field all fun(self: vim.Iter, pred: fun(...): boolean): boolean
---- @field last fun(self: vim.Iter): any
---- @field enumerate fun(self: vim.Iter): vim.Iter
+--- @field any fun(self: vim.Iter, pred: fun(...): boolean): boolean
 --- @field count fun(self: vim.Iter): integer
+--- @field each fun(self: vim.Iter, f: fun(...)): nil
+--- @field enumerate fun(self: vim.Iter): vim.Iter
+--- @field filter fun(self: vim.Iter, f: fun(...): boolean): vim.Iter
+--- @field find fun(self: vim.Iter, f: any): any
+--- @field flatten fun(self: vim.Iter, depth?: integer): vim.IterArray
+--- @field fold fun(self: vim.Iter, init: any, f: fun(acc: any, ...): any): any
+--- @field join fun(self: vim.Iter, delim: string): string
+--- @field last fun(self: vim.Iter): any
+--- @field map fun(self: vim.Iter, f: fun(...): ...): vim.Iter
+--- @field next fun(self: vim.Iter): any
+--- @field nth fun(self: vim.Iter, n: integer): any
+--- @field peek fun(self: vim.Iter): any
+--- @field pop fun(self: vim.Iter): any
+--- @field rev fun(self: vim.Iter): vim.IterArray
+--- @field rfind fun(self: vim.Iter, f: any): any
+--- @field rpeek fun(self: vim.Iter): any
+--- @field rskip fun(self: vim.Iter, n: integer): vim.IterArray
+--- @field skip fun(self: vim.Iter, n: integer|fun(...): boolean): vim.Iter
+--- @field slice fun(self: vim.Iter, first: integer, last: integer): vim.IterArray
+--- @field take fun(self: vim.Iter, n: integer|fun(...): boolean): vim.Iter
+--- @field totable fun(self: vim.Iter): table
+--- @field unique fun(self: vim.Iter, key?: fun(...): any): vim.Iter
 
 --- @class vim.IterArray : vim.Iter
---- @field filter fun(self: vim.IterArray, f: fun(...): boolean): vim.IterArray
---- @field unique fun(self: vim.IterArray, key?: fun(...): any): vim.IterArray
---- @field flatten fun(self: vim.IterArray, depth?: integer): vim.IterArray
---- @field map fun(self: vim.IterArray, f: fun(...): ...): vim.IterArray
---- @field totable fun(self: vim.IterArray): table
---- @field fold fun(self: vim.IterArray, init: any, f: fun(acc: any, ...): any): any
---- @field next fun(self: vim.IterArray): any
---- @field rev fun(self: vim.IterArray): vim.IterArray
---- @field peek fun(self: vim.IterArray): any
---- @field find fun(self: vim.IterArray, f: any): any
---- @field rfind fun(self: vim.IterArray, f: any): any
---- @field take fun(self: vim.IterArray, n: integer|fun(...): boolean): vim.IterArray
---- @field pop fun(self: vim.IterArray): any
---- @field rpeek fun(self: vim.IterArray): any
---- @field skip fun(self: vim.IterArray, n: integer|fun(...): boolean): vim.IterArray
---- @field rskip fun(self: vim.IterArray, n: integer): vim.IterArray
---- @field slice fun(self: vim.IterArray, first: integer, last: integer): vim.IterArray
---- @field last fun(self: vim.IterArray): any
---- @field enumerate fun(self: vim.IterArray): vim.IterArray
 --- @field count fun(self: vim.IterArray): integer
+--- @field enumerate fun(self: vim.IterArray): vim.IterArray
+--- @field filter fun(self: vim.IterArray, f: fun(...): boolean): vim.IterArray
+--- @field find fun(self: vim.IterArray, f: any): any
+--- @field flatten fun(self: vim.IterArray, depth?: integer): vim.IterArray
+--- @field fold fun(self: vim.IterArray, init: any, f: fun(acc: any, ...): any): any
+--- @field last fun(self: vim.IterArray): any
+--- @field map fun(self: vim.IterArray, f: fun(...): ...): vim.IterArray
+--- @field next fun(self: vim.IterArray): any
+--- @field peek fun(self: vim.IterArray): any
+--- @field pop fun(self: vim.IterArray): any
+--- @field rev fun(self: vim.IterArray): vim.IterArray
+--- @field rfind fun(self: vim.IterArray, f: any): any
+--- @field rpeek fun(self: vim.IterArray): any
+--- @field rskip fun(self: vim.IterArray, n: integer): vim.IterArray
+--- @field skip fun(self: vim.IterArray, n: integer|fun(...): boolean): vim.IterArray
+--- @field slice fun(self: vim.IterArray, first: integer, last: integer): vim.IterArray
+--- @field take fun(self: vim.IterArray, n: integer|fun(...): boolean): vim.IterArray
+--- @field totable fun(self: vim.IterArray): table
+--- @field unique fun(self: vim.IterArray, key?: fun(...): any): vim.IterArray
 
 --- @class vim.IterModule
 --- @operator call: fun(src: any, ...): vim.Iter

runtime/lua/vim/_meta/api.gen.lua

@@ -1212,29 +1212,24 @@ function vim.api.nvim_exec2(src, opts) end
 --- - pattern (`string|array?`, default: current file name) `autocmd-pattern`. Not allowed with {buf}.
 function vim.api.nvim_exec_autocmds(event, opts) end
 
---- Sends input-keys to Nvim, subject to various quirks controlled by `mode`
---- flags. This is a blocking call, unlike `nvim_input()`.
+--- Sends input-keys to Nvim, subject to various quirks controlled by `mode` flags. This is
+--- a blocking call, unlike `nvim_input()`.
 ---
 --- On execution error: does not fail, but updates v:errmsg.
 ---
---- To input sequences like [<C-o>] use `nvim_replace_termcodes()` (typically
---- with escape_ks=false) to replace `keycodes`, then pass the result to
---- nvim_feedkeys().
----
---- Example:
+--- To input keycodes like [<C-o>], pass the result of `nvim_replace_termcodes()`:
 ---
 --- ```vim
---- :let key = nvim_replace_termcodes("<C-o>", v:true, v:false, v:true)
+--- :let key = nvim_replace_termcodes('<C-o>', v:true, v:false, v:true)
 --- :call nvim_feedkeys(key, 'n', v:false)
 --- ```
 ---
 --- @see feedkeys()
 --- @see vim_strsave_escape_ks
---- @param keys string to be typed
---- @param mode string behavior flags, see `feedkeys()`
---- @param escape_ks boolean If true, escape K_SPECIAL bytes in `keys`.
---- This should be false if you already used
---- `nvim_replace_termcodes()`, and true otherwise.
+--- @param keys string Keys to send as input.
+--- @param mode string Behavior flags, see `feedkeys()`.
+--- @param escape_ks boolean If true, escape K_SPECIAL bytes in `keys`. Should be false if you used
+--- `nvim_replace_termcodes()`, else true.
 function vim.api.nvim_feedkeys(keys, mode, escape_ks) end
 
 --- Gets the option information for all options.
@@ -2051,13 +2046,10 @@ function vim.api.nvim_paste(data, crlf, phase) end
 --- @param follow boolean If true place cursor at end of inserted text.
 function vim.api.nvim_put(lines, type, after, follow) end
 
---- Replaces terminal codes and `keycodes` ([<CR>], [<Esc>], ...) in a string with
---- the internal representation.
+--- Converts terminal codes and `keycodes` ([<CR>], [<Esc>], …) in a key sequence, to the internal
+--- representation. See also Lua `vim.keycode()`.
 ---
 ---
---- Note:
---- Lua can use |vim.keycode()| instead.
----
 --- @see replace_termcodes
 --- @see cpoptions
 --- @param str string String to be converted.

runtime/lua/vim/lsp.lua

@@ -572,8 +572,8 @@ local function lsp_enable_callback(bufnr)
   end
 end
 
---- Auto-activates LSP in each buffer based on the |lsp-config| `filetypes`, `root_markers`, and
---- `root_dir`.
+--- Enables a [lsp-config]: automatically attaches the client to any buffer based on the config
+--- `filetypes`, `root_markers`, and `root_dir`. See [lsp-activate] for details.
 ---
 --- To disable, pass `enable=false`: Stops related clients and servers (force-stops servers after
 --- a timeout, unless `exit_timeout=false`).