mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2026-03-29 11:52:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: api, messages, lsp, trust

Browse Source 
gen_vimdoc.lua: In prepare for the upcoming release, comment-out the
"Experimental" warning for prerelease features.
This commit is contained in:
Justin M. Keyes
2026-02-12 14:16:47 +01:00
parent 4aeeaa8027
commit b8a976afda
47 changed files with 614 additions and 492 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
runtime/lua/vim/_core/defaults.lua
View File

@@ -445,15 +445,15 @@ do
end, { expr = true, desc = 'Add empty line below cursor' })
end
--- incremental treesitter selection mappings (+ lsp fallback)
--- "Incremental selection" mappings (treesitter + LSP fallback).
do
vim.keymap.set({ 'x' }, '[n', function()
require 'vim.treesitter._select'.select_prev(vim.v.count1)
end, { desc = 'Select previous treesitter node' })
end, { desc = 'Select previous node' })
vim.keymap.set({ 'x' }, ']n', function()
require 'vim.treesitter._select'.select_next(vim.v.count1)
end, { desc = 'Select next treesitter node' })
end, { desc = 'Select next node' })
vim.keymap.set({ 'x', 'o' }, 'an', function()
if vim.treesitter.get_parser(nil, nil, { error = false }) then
@@ -461,7 +461,7 @@ do
else
vim.lsp.buf.selection_range(vim.v.count1)
end
end, { desc = 'Select parent treesitter node or outer incremental lsp selections' })
end, { desc = 'Select parent (outer) node' })
vim.keymap.set({ 'x', 'o' }, 'in', function()
if vim.treesitter.get_parser(nil, nil, { error = false }) then
@@ -469,7 +469,7 @@ do
else
vim.lsp.buf.selection_range(-vim.v.count1)
end
end, { desc = 'Select child treesitter node or inner incremental lsp selections' })
end, { desc = 'Select child (inner) node' })
end
end

8
runtime/lua/vim/_core/shared.lua
View File

@@ -360,7 +360,7 @@ local function key_fn(v, key)
return key and key(v) or v
end
--- Removes duplicate values from a list-like table in-place.
--- Removes duplicate values from a |lua-list| in-place.
---
--- Only the first occurrence of each value is kept.
--- The operation is performed in-place and the input table is modified.
@@ -383,6 +383,7 @@ end
--- -- t is now { {id=1}, {id=2} }
--- ```
---
--- @since 14
--- @generic T
--- @param t T[]
--- @param key? fun(x: T): any Optional hash function to determine uniqueness of values
@@ -482,8 +483,8 @@ local function upper_bound(t, val, lo, hi, key)
return lo
end
--- Search for a position in a sorted list {t}
--- where {val} can be inserted while keeping the list sorted.
--- Search for a position in a sorted |lua-list| {t} where {val} can be inserted while keeping the
--- list sorted.
---
--- Use {bound} to determine whether to return the first or the last position,
--- defaults to "lower", i.e., the first position.
@@ -514,6 +515,7 @@ end
--- print(t[i]) -- { 3, 3, 3 }
--- end
--- ```
---@since 14
---@generic T
---@param t T[] A comparable list.
---@param val T The value to search.

6
runtime/lua/vim/_core/ui2.lua
View File

@@ -11,7 +11,7 @@
--- ---@type 'cmd'|'msg' Default message target, either in the
--- ---cmdline or in a separate ephemeral message window.
--- ---@type string|table<string, 'cmd'|'msg'|'pager'> Default message target
--- or table mapping |ui-messages| kinds and triggers to a target.
--- ---or table mapping |ui-messages| kinds and triggers to a target.
--- targets = 'cmd',
--- timeout = 4000, -- Time a message is visible in the message window.
--- },
@@ -32,7 +32,9 @@
---
---Rather than a |hit-enter-prompt|, messages shown in the cmdline area that do
---not fit are appended with a `[+x]` "spill" indicator, where `x` indicates the
---spilled lines. To see the full message, the |g<| command can be used.
---spilled lines. To see the full message, use either:
--- - ENTER immediately after a message from interactive |:| cmdline.
--- - |g<| at any time.
local api = vim.api
local M = {

39
runtime/lua/vim/_meta/api.lua generated
View File

@@ -1703,26 +1703,19 @@ function vim.api.nvim_notify(msg, log_level, opts) end
--- @return integer # Channel id, or 0 on error
function vim.api.nvim_open_term(buffer, opts) end
--- Opens a new split window, or a floating window if `relative` is specified,
--- or an external window (managed by the UI) if `external` is specified.
--- Opens a new split window, floating window, or external window.
---
--- Floats are windows that are drawn above the split layout, at some anchor
--- position in some other window. Floats can be drawn internally or by external
--- GUI with the `ui-multigrid` extension. External windows are only supported
--- with multigrid GUIs, and are displayed as separate top-level windows.
---
--- For a general overview of floats, see `api-floatwin`.
---
--- The `width` and `height` of the new window must be specified when opening
--- a floating window, but are optional for normal windows.
---
--- If `relative` and `external` are omitted, a normal "split" window is created.
--- The `win` property determines which window will be split. If no `win` is
--- provided or `win == 0`, a window will be created adjacent to the current window.
--- If -1 is provided, a top-level split will be created. `vertical` and `split` are
--- only valid for normal windows, and are used to control split direction. For `vertical`,
--- the exact direction is determined by 'splitright' and 'splitbelow'.
--- Split windows cannot have `bufpos`, `row`, `col`, `border`, `title`, `footer` properties.
--- - Specify `relative` to create a floating window. Floats are drawn over the split layout,
--- relative to a position in some other window. See `api-floatwin`.
--- - Floats must specify `width` and `height`.
--- - Specify `external` to create an external window. External windows are displayed as separate
--- top-level windows managed by the `ui-multigrid` UI (not Nvim).
--- - If `relative` and `external` are omitted, a normal "split" window is created.
--- - The `win` key decides which window to split. If nil or 0, the split will be adjacent to
--- the current window. If -1, a top-level split will be created.
--- - Use `vertical` and `split` to control split direction. For `vertical`, the exact direction
--- is determined by 'splitright' and 'splitbelow'.
--- - Split windows cannot have `bufpos`, `row`, `col`, `border`, `title`, `footer`.
---
--- With relative=editor (row=0,col=0) refers to the top-left corner of the
--- screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right
@@ -2492,11 +2485,11 @@ function vim.api.nvim_win_is_valid(window) end
--- @param buffer integer Buffer id
function vim.api.nvim_win_set_buf(window, buffer) end
--- Reconfigures the layout of a window.
--- Reconfigures the layout and properties of a window.
---
--- - Absent (`nil`) keys will not be changed.
--- - `row` / `col` / `relative` must be reconfigured together.
--- - Cannot be used to move the last window in a tabpage to a different one.
--- - Updates only the given keys; unspecified (`nil`) keys will not be changed.
--- - Keys `row` / `col` / `relative` must be specified together.
--- - Cannot move the last window in a tabpage to a different one.
---
--- Example: to convert a floating window to a "normal" split window, specify the `win` field:
---

3
runtime/lua/vim/_meta/options.lua generated
View File

@@ -3159,6 +3159,7 @@ vim.go.gp = vim.go.grepprg
---
--- ```vim
--- highlight Cursor gui=reverse guifg=NONE guibg=NONE
--- " Note: gui=reverse overrides colors.
--- highlight Cursor gui=NONE guifg=bg guibg=fg
--- ```
---
@@ -3240,7 +3241,7 @@ vim.go.gcr = vim.go.guicursor
---
---
--- @type string
vim.o.guifont = "Source Code Pro,DejaVu Sans Mono,Courier New,monospace"
vim.o.guifont = "DFLT_GFN"
vim.o.gfn = vim.o.guifont
vim.go.guifont = vim.o.guifont
vim.go.gfn = vim.go.guifont

22
runtime/lua/vim/_meta/vvars.lua generated
View File

@@ -6,24 +6,26 @@ error('Cannot require a meta file')
--- @class vim.v
vim.v = ...
--- The list of file arguments passed on the command line at startup.
---
--- Each filename is expanded to an absolute path, so that v:argf
--- remains valid even if the current working directory changes later.
--- File arguments (expanded to absolute paths) given at startup.
---
--- Unlike `v:argv`, this does not include option arguments
--- such as `-u`, `--cmd`, or `+cmd`. Unlike `argv()`, it is not
--- affected by later `:args`, `:argadd`, or plugin modifications.
--- It also handles the `--` separator correctly, including only
--- files specified after it.
---
--- This is a read-only snapshot of the original startup file arguments.
--- Example:
--- ```
--- nvim file1.txt +ls -- file2.txt
--- :echo v:argf
--- " ['/path/to/cwd/file1.txt', '/path/to/cwd/file2.txt']
--- ```
--- @type string[]
vim.v.argf = ...
--- The command line arguments Vim was invoked with. This is a
--- list of strings. The first item is the Vim command.
--- See `v:progpath` for the command with full path.
--- Command line arguments (`-u`, `--cmd`, `+cmd`, …) Nvim was
--- invoked with. The first item is the Nvim command.
---
--- See `v:progpath` to get the full path to Nvim.
--- See `v:argf` to get only file args, without other options.
--- @type string[]
vim.v.argv = ...

23
runtime/lua/vim/iter.lua
View File

@@ -243,6 +243,7 @@ end
--- -- { {id=1}, {id=2} }
--- ```
---
---@since 14
---@param key? fun(...):any Optional hash function to determine uniqueness of values.
---@return Iter
---@see |vim.list.unique()|
@@ -282,6 +283,7 @@ end
--- -- error: attempt to flatten a dict-like table
--- ```
---
---@since 12
---@param depth? number Depth to which |list-iterator| should be flattened
--- (defaults to 1)
---@return Iter
@@ -331,6 +333,7 @@ end
--- -- { 6, 12 }
--- ```
---
---@since 12
---@param f fun(...):...:any Mapping function. Takes all values returned from
--- the previous stage in the pipeline as arguments
--- and returns one or more new values, which are used
@@ -399,6 +402,7 @@ end
---
--- For functions with side effects. To modify the values in the iterator, use |Iter:map()|.
---
---@since 12
---@param f fun(...) Function to execute for each item in the pipeline.
--- Takes all of the values returned by the previous stage
--- in the pipeline as arguments.
@@ -446,6 +450,7 @@ end
--- To create a map-like table with arbitrary keys, use |Iter:fold()|.
---
---
---@since 12
---@return table
function Iter:totable()
local t = {}
@@ -498,6 +503,7 @@ end
---
--- Consumes the iterator.
---
--- @since 12
--- @param delim string Delimiter
--- @return string
function Iter:join(delim)
@@ -527,6 +533,7 @@ end
---
---@generic A
---
---@since 12
---@param init A Initial value of the accumulator.
---@param f fun(acc:A, ...):A Accumulation function.
---@return A
@@ -572,6 +579,7 @@ end
---
--- ```
---
---@since 12
---@return any
function Iter:next()
if self._peeked then
@@ -606,6 +614,7 @@ end
---
--- ```
---
---@since 12
---@return Iter
function Iter:rev()
error('rev() requires an array-like table')
@@ -637,6 +646,7 @@ end
---
--- ```
---
---@since 12
---@return any
function Iter:peek()
if not self._peeked then
@@ -674,6 +684,7 @@ end
--- -- 12
---
--- ```
---@since 12
---@param f any
---@return any
function Iter:find(f)
@@ -720,6 +731,7 @@ end
---
---@see |Iter:find()|
---
---@since 12
---@param f any
---@return any
---@diagnostic disable-next-line: unused-local
@@ -769,6 +781,7 @@ end
--- -- nil
--- ```
---
---@since 12
---@param n integer|fun(...):boolean Number of values to take or a predicate.
---@return Iter
function Iter:take(n)
@@ -828,6 +841,7 @@ end
--- -- 3
--- ```
---
---@since 12
---@return any
function Iter:pop()
error('pop() requires an array-like table')
@@ -858,6 +872,7 @@ end
---
---@see |Iter:last()|
---
---@since 12
---@return any
function Iter:rpeek()
error('rpeek() requires an array-like table')
@@ -891,6 +906,7 @@ end
--- -- 12
--- ```
---
---@since 12
---@param n integer|fun(...):boolean Number of values to skip or a predicate.
---@return Iter
function Iter:skip(n)
@@ -956,6 +972,7 @@ end
--- -- 3
--- ```
---
---@since 12
---@param n number Number of values to skip.
---@return Iter
---@diagnostic disable-next-line: unused-local
@@ -993,6 +1010,7 @@ end
--- -- 3
--- ```
---
---@since 12
---@param n number Index of the value to return. May be negative if the source is a |list-iterator|.
---@return any
function Iter:nth(n)
@@ -1007,6 +1025,7 @@ end
---
--- Equivalent to `:skip(first - 1):rskip(len - last + 1)`.
---
---@since 12
---@param first number
---@param last number
---@return Iter
@@ -1022,6 +1041,7 @@ end
--- Returns true if any of the items in the iterator match the given predicate.
---
---@since 12
---@param pred fun(...):boolean Predicate function. Takes all values returned from the previous
--- stage in the pipeline as arguments and returns true if the
--- predicate matches.
@@ -1046,6 +1066,7 @@ end
--- Returns true if all items in the iterator match the given predicate.
---
---@since 12
---@param pred fun(...):boolean Predicate function. Takes all values returned from the previous
--- stage in the pipeline as arguments and returns true if the
--- predicate matches.
@@ -1083,6 +1104,7 @@ end
---
--- ```
---
---@since 12
---@see |Iter:rpeek()|
---
---@return any
@@ -1135,6 +1157,7 @@ end
---
--- ```
---
---@since 12
---@return Iter
function Iter:enumerate()
local i = 0

6
runtime/lua/vim/lsp.lua
View File

@@ -1046,13 +1046,11 @@ end
--- ```
---
--- By default asks the server to shutdown, unless stop was requested already for this client (then
--- force-shutdown is attempted, unless `exit_timeout=false`).
--- force-stop is attempted, unless `exit_timeout=false`).
---
---@deprecated
---@param client_id integer|integer[]|vim.lsp.Client[] id, list of id's, or list of |vim.lsp.Client| objects
---@param force? boolean|integer Whether to shutdown forcefully.
--- If `force` is a number, it will be treated as the time in milliseconds to
--- wait before forcing the shutdown.
---@param force? boolean|integer See |Client:stop()|
function lsp.stop_client(client_id, force)
vim.deprecate('vim.lsp.stop_client()', 'vim.lsp.Client:stop()', '0.13')
--- @type integer[]|vim.lsp.Client[]

35
runtime/lua/vim/lsp/client.lua
View File

@@ -68,9 +68,11 @@ local all_clients = {}
--- (default: `true`)
--- @field detached? boolean
---
--- Milliseconds to wait for server to exit cleanly after sending the "shutdown" request before
--- sending kill -15. If set to false, waits indefinitely. If set to true, nvim will kill the
--- server immediately.
--- Decides if/when to force-stop the server after sending the "shutdown" request. See |Client:stop()|.
--- Note: when Nvim itself is exiting,
--- - `false`: Nvim will not force-stop LSP server(s).
--- - `true`: Nvim will force-stop LSP server(s) that did not comply with the "shutdown" request.
--- - `number`: Nvim will wait up to `exit_timeout` milliseconds before performing force-stop.
--- (default: `false`)
--- @field exit_timeout? integer|boolean
---
@@ -156,9 +158,7 @@ local all_clients = {}
--- Capabilities provided at runtime (after startup).
--- @field dynamic_capabilities lsp.DynamicCapabilities
---
--- Milliseconds to wait for server to exit cleanly after sending the "shutdown" request before
--- sending kill -15. If set to false, waits indefinitely. If set to true, nvim will kill the
--- server immediately.
--- See [vim.lsp.ClientConfig].
--- (default: `false`)
--- @field exit_timeout integer|boolean
---
@@ -852,20 +852,19 @@ end
--- Stops a client, optionally with force after a timeout.
---
--- By default, it will request the server to shutdown, then force a shutdown
--- if the server has not exited after `self.exit_timeout` milliseconds. If
--- you request to stop a client which has previously been requested to
--- shutdown, it will automatically escalate and force shutdown immediately,
--- regardless of the value of `force` (or `self.exit_timeout` if `nil`).
--- By default this sends a "shutdown" request to the server, escalating to force-stop if the server
--- has not exited after `self.exit_timeout` milliseconds (unless `exit_timeout=false`).
--- Calling stop() on a client that was previously requested to shutdown, will escalate to
--- force-stop immediately, regardless of `force` (or `self.exit_timeout` if `force=nil`).
---
--- Note: Forcing shutdown while a server is busy writing out project or index
--- files can lead to file corruption.
--- Note: Forcing shutdown while a server is busy writing out project or index files can lead to
--- file corruption.
---
--- @param force? integer|boolean Time in milliseconds to wait before forcing
--- a shutdown. If false, only request the
--- server to shutdown, but don't force it. If
--- true, force a shutdown immediately.
--- (default: `self.exit_timeout`)
--- @param force? integer|boolean (default: `self.exit_timeout`) Decides whether to force-stop the server.
--- - `nil`: Defaults to `exit_timeout` from |vim.lsp.ClientConfig|.
--- - `true`: Force-stop after "shutdown" request.
--- - `false`: Do not force-stop after "shutdown" request.
--- - number: Wait up to `force` milliseconds before force-stop.
function Client:stop(force)
validate('force', force, { 'number', 'boolean' }, true)

17
runtime/lua/vim/lsp/completion.lua
View File

@@ -6,7 +6,7 @@
---
--- Example: activate LSP-driven auto-completion:
--- ```lua
--- -- Works best with completeopt=noselect.
--- -- Works best if 'completeopt' has "noselect".
--- -- Use CTRL-Y to select an item. |complete_CTRL-Y|
--- vim.cmd[[set completeopt+=menuone,noselect,popup]]
--- vim.lsp.start({
@@ -1159,15 +1159,14 @@ end
--- Enables or disables completions from the given language client in the given
--- buffer. Effects of enabling completions are:
---
--- - Calling |vim.lsp.completion.get()| uses the enabled clients to retrieve
--- completion candidates
--- - Calling |vim.lsp.completion.get()| uses the enabled clients to retrieve completion candidates.
--- - Selecting a completion item shows a preview popup ("completionItem/resolve") if 'completeopt'
--- has "popup".
--- - Accepting a completion item using `<c-y>` applies side effects like expanding snippets,
--- text edits (e.g. insert import statements) and executing associated commands. This works for
--- completions triggered via autotrigger, 'omnifunc' or [vim.lsp.completion.get()].
---
--- - Accepting a completion candidate using `<c-y>` applies side effects like
--- expanding snippets, text edits (e.g. insert import statements) and
--- executing associated commands. This works for completions triggered via
--- autotrigger, omnifunc or completion.get()
---
--- Example: |lsp-attach| |lsp-completion|
--- Examples: |lsp-attach| |lsp-completion|
---
--- Note: the behavior of `autotrigger=true` is controlled by the LSP `triggerCharacters` field. You
--- can override it on LspAttach, see |lsp-autocompletion|.

5
runtime/lua/vim/pack.lua
View File

@@ -1204,9 +1204,8 @@ end
--- @field offline? boolean Whether to skip downloading new updates. Default: `false`.
---
--- How to compute a new plugin revision. One of:
--- - "version" (default) - use latest revision matching `version` from plugin specification.
--- - "lockfile" - use revision from the lockfile. Useful for reverting or performing controlled
--- update.
--- - "version" (default): use latest revision matching `version` from plugin specification.
--- - "lockfile": use revision from the lockfile. For reverting or performing controlled update.
--- @field target? string
--- Update plugins

7
runtime/lua/vim/secure.lua
View File

@@ -162,9 +162,10 @@ end
--- @class vim.trust.opts
--- @inlinedoc
---
--- - `'allow'` to add a file to the trust database and trust it,
--- - `'deny'` to add a file to the trust database and deny it,
--- - `'remove'` to remove file from the trust database
--- One of:
--- - `'allow'` to add a file to the trust database and trust it,
--- - `'deny'` to add a file to the trust database and deny it,
--- - `'remove'` to remove file from the trust database
--- @field action 'allow'|'deny'|'remove'
---
--- Path to a file to update. Mutually exclusive with {bufnr}.

6
runtime/lua/vim/treesitter/query.lua
View File

@@ -1193,10 +1193,8 @@ end
--- parsers.
---
--- If you move the cursor to a capture name ("@foo"), text matching the capture is highlighted
--- with |hl-DiagnosticVirtualTextHint| in the source buffer.
---
--- The query editor is a scratch buffer, use `:write` to save it. You can find example queries
--- at `$VIMRUNTIME/queries/`.
--- with |hl-DiagnosticVirtualTextHint| in the source buffer. The query editor is a scratch buffer,
--- use `:write` to save it. You can find example queries at `$VIMRUNTIME/queries/`.
---
--- @param lang? string language to open the query editor for. If omitted, inferred from the current buffer's filetype.
function M.edit(lang)