docs: api, lsp, messages, intro #38327

1 files changed, 98 insertions, 112 deletions

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 3057cd8998..c3a7170b07 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -831,26 +831,20 @@ function vim.api.nvim_call_function(fn, args) end
 --- @param data string Data to write. 8-bit clean: may contain NUL bytes.
 function vim.api.nvim_chan_send(chan, data) end
 
---- Clears all autocommands selected by {opts}. To delete autocmds see `nvim_del_autocmd()`.
+--- Clears all autocommands matching the {opts} query. To delete autocmds see `nvim_del_autocmd()`.
 ---
---- @param opts vim.api.keyset.clear_autocmds Parameters
---- - event: (vim.api.keyset.events|vim.api.keyset.events[])
----      Examples:
----      - event: "pat1"
----      - event: { "pat1" }
----      - event: { "pat1", "pat2", "pat3" }
---- - pattern: (string|table)
----     - pattern or patterns to match exactly.
----         - For example, if you have `*.py` as that pattern for the autocmd,
----           you must pass `*.py` exactly to clear it. `test.py` will not
----           match the pattern.
----     - defaults to clearing all patterns.
----     - NOTE: Cannot be used with {buffer}
---- - buffer: (bufnr)
----     - clear only `autocmd-buflocal` autocommands.
----     - NOTE: Cannot be used with {pattern}
---- - group: (string|int) The augroup name or id.
----     - NOTE: If not passed, will only delete autocmds *not* in any group.
+--- @param opts vim.api.keyset.clear_autocmds Optional parameters:
+--- - event: (`vim.api.keyset.events|vim.api.keyset.events[]?`)
+---   Examples:
+---   - event: "pat1"
+---   - event: { "pat1" }
+---   - event: { "pat1", "pat2", "pat3" }
+--- - pattern: (`string|table?`) Filter by patterns (exact match). Not allowed with {buffer}.
+---   - Example: if you have `*.py` as that pattern for the autocmd, you must pass `*.py`
+---     exactly to clear it. `test.py` will not match the pattern.
+--- - buffer: (`integer?`) Select `autocmd-buflocal` autocommands. Not allowed with {pattern}.
+--- - group: (`string|int?`) Group name or id.
+---   - NOTE: If not given, matches autocmds *not* in any group.
 function vim.api.nvim_clear_autocmds(opts) end
 
 --- Executes an Ex command `cmd`, specified as a Dict with the same structure as returned by
@@ -906,16 +900,15 @@ function vim.api.nvim_command_output(command) end
 ---
 --- ```lua
 --- local id = vim.api.nvim_create_augroup('my.lsp.config', {
----     clear = false
+---   clear = false
 --- })
 --- ```
 ---
 --- @see `:help autocmd-groups`
---- @param name string String: The name of the group
---- @param opts vim.api.keyset.create_augroup Dict Parameters
---- - clear (bool) optional: defaults to true. Clear existing
---- commands if the group already exists `autocmd-groups`.
---- @return integer # Integer id of the created group.
+--- @param name string Group name
+--- @param opts vim.api.keyset.create_augroup Optional parameters:
+--- - clear (`boolean?`, default: true) Clear existing commands in the group `autocmd-groups`.
+--- @return integer # Group id.
 function vim.api.nvim_create_augroup(name, opts) end
 
 --- Creates an `autocommand` event handler, defined by `callback` (Lua function or Vimscript
@@ -952,28 +945,24 @@ function vim.api.nvim_create_augroup(name, opts) end
 --- @see vim.api.nvim_del_autocmd
 --- @param event vim.api.keyset.events|vim.api.keyset.events[] Event(s) that will trigger the handler (`callback` or `command`).
 --- @param opts vim.api.keyset.create_autocmd Options dict:
---- - group (string|integer) optional: autocommand group name or id to match against.
---- - pattern (string|array) optional: pattern(s) to match literally `autocmd-pattern`.
---- - buffer (integer) optional: buffer number for buffer-local autocommands
---- `autocmd-buflocal`. Cannot be used with {pattern}.
---- - desc (string) optional: description (for documentation and troubleshooting).
---- - callback (function|string) optional: Lua function (or Vimscript function name, if
---- string) called when the event(s) is triggered. Lua callback can return a truthy
---- value (not `false` or `nil`) to delete the autocommand, and receives one argument, a
---- table with these keys: [event-args]()
----     - id: (number) autocommand id
----     - event: (vim.api.keyset.events) name of the triggered event `autocmd-events`
----     - group: (number|nil) autocommand group id, if any
----     - file: (string) [<afile>] (not expanded to a full path)
----     - match: (string) [<amatch>] (expanded to a full path)
----     - buf: (number) [<abuf>]
----     - data: (any) arbitrary data passed from [nvim_exec_autocmds()] [event-data]()
---- - command (string) optional: Vim command to execute on event. Cannot be used with
---- {callback}
---- - once (boolean) optional: defaults to false. Run the autocommand
---- only once `autocmd-once`.
---- - nested (boolean) optional: defaults to false. Run nested
---- autocommands `autocmd-nested`.
+--- - buffer (`integer?`) Buffer id for buffer-local autocommands `autocmd-buflocal`.
+---   Not allowed with {pattern}.
+--- - callback (`function|string?`) Lua function (or Vimscript function name, if string)
+---   called when the event(s) is triggered. Lua callback can return `lua-truthy` to delete
+---   the autocommand. Callback receives one argument, a table with keys: [event-args]()
+---     - id: (`number`) Autocommand id
+---     - event: (`vim.api.keyset.events`) Name of the triggered event `autocmd-events`
+---     - group: (`number?`) Group id, if any
+---     - file: (`string`) [<afile>] (not expanded to a full path)
+---     - match: (`string`) [<amatch>] (expanded to a full path)
+---     - buf: (`number`) [<abuf>]
+---     - data: (`any`) Arbitrary data passed from [nvim_exec_autocmds()] [event-data]()
+--- - command (string?) Vim command executed on event. Not allowed with {callback}.
+--- - desc (`string?`) Description (for documentation and troubleshooting).
+--- - group (`string|integer?`) Group name or id to match against.
+--- - nested (`boolean?`, default: false) Run nested autocommands `autocmd-nested`.
+--- - once (`boolean?`, default: false) Handle the event only once `autocmd-once`.
+--- - pattern (`string|array?`) Pattern(s) to match literally `autocmd-pattern`.
 --- @return integer # Autocommand id (number)
 function vim.api.nvim_create_autocmd(event, opts) end
 
@@ -1047,7 +1036,7 @@ function vim.api.nvim_create_user_command(name, command, opts) end
 --- this group will also be deleted and cleared. This group will no longer exist.
 --- @see vim.api.nvim_del_augroup_by_name
 --- @see vim.api.nvim_create_augroup
---- @param id integer Integer The id of the group.
+--- @param id integer Group id.
 function vim.api.nvim_del_augroup_by_id(id) end
 
 --- Delete an autocommand group by name.
@@ -1055,12 +1044,12 @@ function vim.api.nvim_del_augroup_by_id(id) end
 --- NOTE: behavior differs from `:augroup-delete`. When deleting a group, autocommands contained in
 --- this group will also be deleted and cleared. This group will no longer exist.
 --- @see `:help autocmd-groups`
---- @param name string String The name of the group.
+--- @param name string Group name.
 function vim.api.nvim_del_augroup_by_name(name) end
 
 --- Deletes an autocommand by id.
 ---
---- @param id integer Integer Autocommand id returned by `nvim_create_autocmd()`
+--- @param id integer Autocommand id returned by `nvim_create_autocmd()`
 function vim.api.nvim_del_autocmd(id) end
 
 --- Deletes the current line.
@@ -1097,7 +1086,13 @@ function vim.api.nvim_del_user_command(name) end
 --- @param name string Variable name
 function vim.api.nvim_del_var(name) end
 
---- Prints a message given by a list of `[text, hl_group]` "chunks".
+--- Prints a message given by a list of `[text, hl_group]` "chunks". Emits a `Progress` event if
+--- `kind='progress'`.
+---
+--- Returns a message-id, which can be given in later calls to update an existing message. The
+--- message-id is an autogenerated integer, or a user-defined string. The id "address space" is
+--- global, so plugins specifying a string id should use qualified names such as "my.msg.id" to
+--- avoid unintentional conflicts.
 ---
 --- Example:
 --- ```lua
@@ -1108,23 +1103,24 @@ function vim.api.nvim_del_var(name) end
 --- the (optional) name or ID `hl_group`.
 --- @param history boolean if true, add to `message-history`.
 --- @param opts vim.api.keyset.echo_opts Optional parameters.
---- - id: message id for updating existing message.
---- - err: Treat the message like `:echoerr`. Sets `hl_group` to `hl-ErrorMsg` by default.
---- - kind: Set the `ui-messages` kind with which this message will be emitted.
---- - verbose: Message is controlled by the 'verbose' option. Nvim invoked with `-V3log`
----   will write the message to the "log" file instead of standard output.
---- - title: The title for `progress-message`.
---- - status: Current status of the `progress-message`. Can be
----   one of the following values
----   - success: The progress item completed successfully
----   - running: The progress is ongoing
----   - failed: The progress item failed
----   - cancel: The progressing process should be canceled. NOTE: Cancel must be handled by
----     progress initiator by listening for the `Progress` event
---- - percent: How much progress is done on the progress message
---- - data: dictionary containing additional information
---- @return integer|string # Message id.
---- - -1 means nvim_echo didn't show a message
+--- - data (`table?`) Dict of arbitrary data, available in `Progress` `event-data`.
+--- - err (`boolean?`)  Treat the message like `:echoerr`. Sets `hl_group` to `hl-ErrorMsg` by default.
+--- - id (`integer|string?`) Message-id returned by a previous `nvim_echo` call, or
+---   a user-defined id (string). If existing message has this id, it will be updated
+---   instead of creating a new message.
+--- - kind (`string?`) Decides the `ui-messages` kind in the emitted message. Set "progress"
+---   to emit a `progress-message`.
+--- - percent (`integer?`) `progress-message` percentage.
+--- - status (`string?`) `progress-message` status:
+---   - "success": Process completed successfully.
+---   - "running": Process is ongoing.
+---   - "failed": Process failed.
+---   - "cancel": Process should be cancelled. Progress owner must handle the `Progress`
+---     event to perform the cancellation.
+--- - title (`string?`) Message title. Only for `progress-message` currently.
+--- - verbose (`boolean?`) Message is controlled by the 'verbose' option. `nvim -V3log` will write the
+---   message to the "log" file instead of standard output.
+--- @return integer|string # Message-id, or -1 if message wasn't shown.
 function vim.api.nvim_echo(chunks, history, opts) end
 
 --- @deprecated
@@ -1194,21 +1190,16 @@ function vim.api.nvim_exec(src, output) end
 --- - output: (string|nil) Output if `opts.output` is true.
 function vim.api.nvim_exec2(src, opts) end
 
---- Execute all autocommands for {event} that match the corresponding
----  {opts} `autocmd-execute`.
+--- Executes handlers for {event} that match the corresponding {opts} query. `autocmd-execute`
 --- @see `:help :doautocmd`
---- @param event vim.api.keyset.events|vim.api.keyset.events[] The event or events to execute
---- @param opts vim.api.keyset.exec_autocmds Dict of autocommand options:
---- - group (string|integer) optional: the autocommand group name or
---- id to match against. `autocmd-groups`.
---- - pattern (string|array) optional: defaults to "*" `autocmd-pattern`. Cannot be used
---- with {buffer}.
---- - buffer (integer) optional: buffer number `autocmd-buflocal`. Cannot be used with
---- {pattern}.
---- - modeline (bool) optional: defaults to true. Process the
---- modeline after the autocommands [<nomodeline>].
---- - data (any): arbitrary data to send to the autocommand callback. See
---- `nvim_create_autocmd()` for details.
+--- @param event vim.api.keyset.events|vim.api.keyset.events[] Event(s) to execute.
+--- @param opts vim.api.keyset.exec_autocmds Optional filters:
+--- - group (`string|integer?`) Group name or id to match against. `autocmd-groups`.
+--- - pattern (`string|array?`, default: "*") `autocmd-pattern`. Not allowed with {buffer}.
+--- - buffer (`integer?`) Buffer id `autocmd-buflocal`. Not allowed with {pattern}.
+--- - modeline (`boolean?`, default: true) Process the modeline after the autocommands
+---   [<nomodeline>].
+--- - data (`any`): Arbitrary data passed to the callback. See `nvim_create_autocmd()`.
 function vim.api.nvim_exec_autocmds(event, opts) end
 
 --- Sends input-keys to Nvim, subject to various quirks controlled by `mode`
@@ -1246,9 +1237,12 @@ function vim.api.nvim_feedkeys(keys, mode, escape_ks) end
 --- @return table<string,any> # dict of all options
 function vim.api.nvim_get_all_options_info() end
 
---- Get all autocommands that match the corresponding {opts}.
+--- Gets all autocommands matching ALL criteria in the {opts} query.
+---
+--- Note: When multiple patterns or events are provided they have "OR" semantics (any combination
+--- is matched).
 ---
---- These examples will get autocommands matching ALL the given criteria:
+--- Examples:
 ---
 --- ```lua
 --- -- Matches all criteria
@@ -1264,33 +1258,25 @@ function vim.api.nvim_get_all_options_info() end
 --- })
 --- ```
 ---
---- NOTE: When multiple patterns or events are provided, it will find all the autocommands that
---- match any combination of them.
----
---- @param opts vim.api.keyset.get_autocmds Dict with at least one of the following:
---- - buffer: (integer) Buffer number or list of buffer numbers for buffer local autocommands
---- `autocmd-buflocal`. Cannot be used with {pattern}
---- - event: (vim.api.keyset.events|vim.api.keyset.events[])
----   event or events to match against `autocmd-events`.
---- - id: (integer) Autocommand ID to match.
---- - group: (string|table) the autocommand group name or id to match against.
---- - pattern: (string|table) pattern or patterns to match against `autocmd-pattern`.
---- Cannot be used with {buffer}
---- @return vim.api.keyset.get_autocmds.ret[] # Array of autocommands matching the criteria, with each item
---- containing the following fields:
---- - buffer: (integer) the buffer number.
---- - buflocal: (boolean) true if the autocommand is buffer local.
---- - command: (string) the autocommand command. Note: this will be empty if a callback is set.
---- - callback: (function|string|nil): Lua function or name of a Vim script function
----   which is executed when this autocommand is triggered.
---- - desc: (string) the autocommand description.
---- - event: (vim.api.keyset.events) the autocommand event.
---- - id: (integer) the autocommand id (only when defined with the API).
---- - group: (integer) the autocommand group id.
---- - group_name: (string) the autocommand group name.
---- - once: (boolean) whether the autocommand is only run once.
---- - pattern: (string) the autocommand pattern.
----   If the autocommand is buffer local |autocmd-buffer-local|:
+--- @param opts vim.api.keyset.get_autocmds Dict with at least one of these keys:
+--- - buffer: (`integer[]|integer?`) Buffer id or list of buffer ids, for buffer-local autocommands
+---   `autocmd-buflocal`. Not allowed with {pattern}.
+--- - event: (`vim.api.keyset.events|vim.api.keyset.events[]?`) Event(s) to match `autocmd-events`.
+--- - group: (`string|table?`) Group name or id to match.
+--- - id: (`integer?`) Autocommand ID to match.
+--- - pattern: (`string|table?`) Pattern(s) to match `autocmd-pattern`. Not allowed with {buffer}.
+--- @return vim.api.keyset.get_autocmds.ret[] # Array of matching autocommands, where each item has:
+--- - buffer (`integer?`): Buffer id (only for |autocmd-buffer-local|).
+--- - buflocal (`boolean?`): true if the autocommand is buffer-local |autocmd-buffer-local|.
+--- - callback: (`function|string?`): Event handler: a Lua function or Vimscript function name.
+--- - command: (`string`) Event handler: an Ex-command. Empty if a `callback` is set.
+--- - desc: (`string`) Description.
+--- - event: (`vim.api.keyset.events`) Event name(s).
+--- - group: (`integer`) Group id.
+--- - group_name: (`string`) Group name.
+--- - id: (`integer`) Autocommand id (only when defined with the API).
+--- - once: (`boolean`) true if |autocmd-once| was set.
+--- - pattern: (`string`) Autocommand pattern.
 function vim.api.nvim_get_autocmds(opts) end
 
 --- Gets information about a channel.
@@ -1681,7 +1667,7 @@ function vim.api.nvim_notify(msg, log_level, opts) end
 --- @param config vim.api.keyset.tabpage_config Configuration for the new tabpage. Keys:
 --- - after: Position to insert tabpage (default: -1; after current).
 ---          0 = first, N = after Nth.
---- @return integer # Tabpage handle of the created tabpage
+--- @return integer # |tab-ID| of the new tabpage
 function vim.api.nvim_open_tabpage(buffer, enter, config) end
 
 --- Open a terminal instance in a buffer