From 8b2b1fba2abfb99186e3a1f0123251a3e2eae3fe Mon Sep 17 00:00:00 2001 From: glepnir Date: Fri, 3 May 2024 15:53:13 +0800 Subject: fix(float): missing default highlight for title Problem: there is missing default title highlight when highlight not defined in title text chunk. Solution: when attr is not set use default title highlight group. --- runtime/lua/vim/_meta/api.lua | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 64c67be076..ae43863316 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1731,13 +1731,15 @@ function vim.api.nvim_open_term(buffer, opts) end --- --- • title: Title (optional) in window border, string or list. --- List should consist of `[text, highlight]` tuples. If ---- string, the default highlight group is `FloatTitle`. +--- string, or a tuple lacks a highlight, the default +--- highlight group is `FloatTitle`. --- • title_pos: Title position. Must be set with `title` --- option. Value can be one of "left", "center", or "right". --- Default is `"left"`. --- • footer: Footer (optional) in window border, string or --- list. List should consist of `[text, highlight]` tuples. ---- If string, the default highlight group is `FloatFooter`. +--- If string, or a tuple lacks a highlight, the default +--- highlight group is `FloatFooter`. --- • footer_pos: Footer position. Must be set with `footer` --- option. Value can be one of "left", "center", or "right". --- Default is `"left"`. -- cgit From 8c5af0eb85a3932f6ca018d2aa681521369a26be Mon Sep 17 00:00:00 2001 From: dundargoc <33953936+dundargoc@users.noreply.github.com> Date: Fri, 7 Jun 2024 04:55:14 +0200 Subject: docs: misc (#28837) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Danymat Co-authored-by: Gregory Anders Co-authored-by: Jakub Okoński Co-authored-by: John L. Villalovos Co-authored-by: Maria José Solano Co-authored-by: Michaili K Co-authored-by: TheLeoP Co-authored-by: Tobias Schmitz Co-authored-by: W20MC <157727813+W20MC@users.noreply.github.com> Co-authored-by: Will Hopkins Co-authored-by: Yifan Hu <141280278+b0ae989c@users.noreply.github.com> Co-authored-by: glepnir Co-authored-by: prljav <74116121+prljav@users.noreply.github.com> --- runtime/lua/vim/_meta/api.lua | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index c99eefa4f6..bb27ee4269 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -276,14 +276,14 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- @return boolean function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end ---- call a function with buffer as temporary current buffer +--- Call a function with buffer as temporary current buffer. --- --- This temporarily switches current buffer to "buffer". If the current ---- window already shows "buffer", the window is not switched If a window ---- inside the current tabpage (including a float) already shows the buffer ---- One of these windows will be set as current window temporarily. Otherwise ---- a temporary scratch window (called the "autocmd window" for historical ---- reasons) will be used. +--- window already shows "buffer", the window is not switched. If a window +--- inside the current tabpage (including a float) already shows the buffer, +--- then one of these windows will be set as current window temporarily. +--- Otherwise a temporary scratch window (called the "autocmd window" for +--- historical reasons) will be used. --- --- This is useful e.g. to call Vimscript functions that only work with the --- current buffer/window currently, like `termopen()`. @@ -1953,7 +1953,7 @@ function vim.api.nvim_set_current_win(window) end --- --- • on_win: called when starting to redraw a specific window. --- ``` ---- ["win", winid, bufnr, topline, botline] +--- ["win", winid, bufnr, toprow, botrow] --- ``` --- --- • on_line: called for each buffer line being redrawn. (The -- cgit From f3632e14e3a75114415050ab01c2d04a06036009 Mon Sep 17 00:00:00 2001 From: altermo <107814000+altermo@users.noreply.github.com> Date: Fri, 7 Jun 2024 17:33:40 +0200 Subject: feat: get/set namespace properties #28728 ref https://github.com/neovim/neovim/pull/28432 ref https://github.com/neovim/neovim/issues/28469 --- runtime/lua/vim/_meta/api.lua | 51 ++++++++++++++++--------------------------- 1 file changed, 19 insertions(+), 32 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index bb27ee4269..d91b2d08bf 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -99,6 +99,25 @@ function vim.api.nvim__inspect_cell(grid, row, col) end --- function vim.api.nvim__invalidate_glyph_cache() end +--- @private +--- EXPERIMENTAL: this API will change in the future. +--- +--- Get the properties for namespace +--- +--- @param ns_id integer Namespace +--- @return vim.api.keyset.ns_opts +function vim.api.nvim__ns_get(ns_id) end + +--- @private +--- EXPERIMENTAL: this API will change in the future. +--- +--- Set some properties for namespace +--- +--- @param ns_id integer Namespace +--- @param opts vim.api.keyset.ns_opts Optional parameters to set: +--- • wins: a list of windows to be scoped in +function vim.api.nvim__ns_set(ns_id, opts) end + --- @private --- EXPERIMENTAL: this API may change in the future. --- @@ -144,36 +163,6 @@ function vim.api.nvim__stats() end --- @return any function vim.api.nvim__unpack(str) end ---- @private ---- EXPERIMENTAL: this API will change in the future. ---- ---- Scopes a namespace to the a window, so extmarks in the namespace will be ---- active only in the given window. ---- ---- @param window integer Window handle, or 0 for current window ---- @param ns_id integer Namespace ---- @return boolean -function vim.api.nvim__win_add_ns(window, ns_id) end - ---- @private ---- EXPERIMENTAL: this API will change in the future. ---- ---- Unscopes a namespace (un-binds it from the given scope). ---- ---- @param window integer Window handle, or 0 for current window ---- @param ns_id integer the namespace to remove ---- @return boolean -function vim.api.nvim__win_del_ns(window, ns_id) end - ---- @private ---- EXPERIMENTAL: this API will change in the future. ---- ---- Gets the namespace scopes for a given window. ---- ---- @param window integer Window handle, or 0 for current window ---- @return integer[] -function vim.api.nvim__win_get_ns(window) end - --- Adds a highlight to buffer. --- --- Useful for plugins that dynamically generate highlights to a buffer (like @@ -686,8 +675,6 @@ function vim.api.nvim_buf_line_count(buffer) end --- • url: A URL to associate with this extmark. In the TUI, the --- OSC 8 control sequence is used to generate a clickable --- hyperlink to this URL. ---- • scoped: boolean (EXPERIMENTAL) enables "scoping" for the ---- extmark. See `nvim__win_add_ns()` --- @return integer function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end -- cgit From 6e28589e00a32045d5a62654151299802e40fdb0 Mon Sep 17 00:00:00 2001 From: dundargoc <33953936+dundargoc@users.noreply.github.com> Date: Sat, 15 Jun 2024 01:04:27 +0200 Subject: docs: misc (#29229) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Ilia Choly Co-authored-by: Jose Pedro Oliveira Co-authored-by: Maria José Solano Co-authored-by: zeertzjq --- runtime/lua/vim/_meta/api.lua | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index d91b2d08bf..1b70cc275f 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1910,7 +1910,7 @@ function vim.api.nvim_set_current_win(window) end --- Note: this function should not be called often. Rather, the callbacks --- themselves can be used to throttle unneeded callbacks. the `on_start` --- callback can return `false` to disable the provider until the next redraw. ---- Similarly, return `false` in `on_win` will skip the `on_lines` calls for +--- Similarly, return `false` in `on_win` will skip the `on_line` calls for --- that window (but any extmarks set in `on_win` will still be used). A --- plugin managing multiple sources of decoration should ideally only set one --- provider, and merge the sources internally. You can use multiple `ns_id` @@ -1919,10 +1919,10 @@ function vim.api.nvim_set_current_win(window) end --- Note: doing anything other than setting extmarks is considered --- experimental. Doing things like changing options are not explicitly --- forbidden, but is likely to have unexpected consequences (such as 100% CPU ---- consumption). doing `vim.rpcnotify` should be OK, but `vim.rpcrequest` is +--- consumption). Doing `vim.rpcnotify` should be OK, but `vim.rpcrequest` is --- quite dubious for the moment. --- ---- Note: It is not allowed to remove or update extmarks in 'on_line' +--- Note: It is not allowed to remove or update extmarks in `on_line` --- callbacks. --- --- @param ns_id integer Namespace id from `nvim_create_namespace()` -- cgit From a901fb875f69ff4e3033f883d5b8665eb608a586 Mon Sep 17 00:00:00 2001 From: Maria José Solano Date: Fri, 16 Aug 2024 08:36:23 -0700 Subject: fix(docs): add missing properties to hl_info #30032 --- runtime/lua/vim/_meta/api.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 1b70cc275f..7dace2f88a 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1321,7 +1321,7 @@ function vim.api.nvim_get_current_win() end --- of effective definition `:hi-link`. --- • create: (boolean, default true) When highlight group doesn't --- exist create it. ---- @return vim.api.keyset.hl_info +--- @return vim.api.keyset.get_hl_info function vim.api.nvim_get_hl(ns_id, opts) end --- @deprecated -- cgit From b8135a76b71f1af0d708e3dc58ccb58abad59f7c Mon Sep 17 00:00:00 2001 From: JonnyKong Date: Sun, 25 Aug 2024 03:57:02 +0000 Subject: fix(docs): wrong return value annotation for `nvim_buf_get_extmarks` --- runtime/lua/vim/_meta/api.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 7dace2f88a..871521db43 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -378,7 +378,7 @@ function vim.api.nvim_buf_get_commands(buffer, opts) end --- • details: Whether to include the details dict --- • hl_name: Whether to include highlight group name instead of --- id, true if omitted ---- @return vim.api.keyset.get_extmark_item +--- @return vim.api.keyset.get_extmark_item_by_id function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- Gets `extmarks` in "traversal order" from a `charwise` region defined by -- cgit From 29bceb4f758097cc6b66726f1dcd3967ad170e35 Mon Sep 17 00:00:00 2001 From: Evgeni Chasnovski Date: Sun, 22 Sep 2024 13:51:22 +0300 Subject: docs(api): nvim_get_runtime_file preserves 'runtimepath' order #30454 --- runtime/lua/vim/_meta/api.lua | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 871521db43..1d8354f6f7 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1454,11 +1454,11 @@ function vim.api.nvim_get_proc(pid) end --- @return any[] function vim.api.nvim_get_proc_children(pid) end ---- Find files in runtime directories +--- Finds files in runtime directories, in 'runtimepath' order. --- --- "name" can contain wildcards. For example ---- nvim_get_runtime_file("colors/*.vim", true) will return all color scheme ---- files. Always use forward slashes (/) in the search pattern for +--- `nvim_get_runtime_file("colors/*.{vim,lua}", true)` will return all color +--- scheme files. Always use forward slashes (/) in the search pattern for --- subdirectories regardless of platform. --- --- It is not an error to not find any files. An empty array is returned then. -- cgit From 737f58e23230ea14f1648ac1fc7f442ea0f8563c Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Fri, 20 Sep 2024 07:34:50 +0200 Subject: refactor(api)!: rename Dictionary => Dict In the api_info() output: :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val') ... {'return_type': 'ArrayOf(Integer, 2)', 'name': 'nvim_win_get_position', 'method': v:true, 'parameters': [['Window', 'window']], 'since': 1} The `ArrayOf(Integer, 2)` return type didn't break clients when we added it, which is evidence that clients don't use the `return_type` field, thus renaming Dictionary => Dict in api_info() is not (in practice) a breaking change. --- runtime/lua/vim/_meta/api.lua | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 1d8354f6f7..f14606fc99 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -64,14 +64,14 @@ function vim.api.nvim__id(obj) end function vim.api.nvim__id_array(arr) end --- @private ---- Returns dictionary given as argument. +--- Returns dict given as argument. --- --- This API function is used for testing. One should not rely on its presence --- in plugins. --- ---- @param dct table Dictionary to return. +--- @param dct table Dict to return. --- @return table -function vim.api.nvim__id_dictionary(dct) end +function vim.api.nvim__id_dict(dct) end --- @private --- Returns floating-point value given as argument. @@ -777,7 +777,7 @@ function vim.api.nvim_buf_set_virtual_text(buffer, src_id, line, chunks, opts) e --- --- On execution error: fails with Vimscript error, updates v:errmsg. --- ---- @param dict any Dictionary, or String evaluating to a Vimscript `self` dict +--- @param dict any Dict, or String evaluating to a Vimscript `self` dict --- @param fn string Name of the function defined on the Vimscript dict --- @param args any[] Function arguments packed in an Array --- @return any @@ -830,8 +830,8 @@ function vim.api.nvim_clear_autocmds(opts) end --- Executes an Ex command. --- ---- Unlike `nvim_command()` this command takes a structured Dictionary instead ---- of a String. This allows for easier construction and manipulation of an Ex +--- Unlike `nvim_command()` this command takes a structured Dict instead of a +--- String. This allows for easier construction and manipulation of an Ex --- command. This also allows for things such as having spaces inside a --- command argument, expanding filenames in a command that otherwise doesn't --- expand filenames, etc. Command arguments may also be Number, Boolean or @@ -844,10 +844,10 @@ function vim.api.nvim_clear_autocmds(opts) end --- --- On execution error: fails with Vimscript error, updates v:errmsg. --- ---- @param cmd vim.api.keyset.cmd Command to execute. Must be a Dictionary that can contain the ---- same values as the return value of `nvim_parse_cmd()` except ---- "addr", "nargs" and "nextcmd" which are ignored if provided. ---- All values except for "cmd" are optional. +--- @param cmd vim.api.keyset.cmd Command to execute. Must be a Dict that can contain the same +--- values as the return value of `nvim_parse_cmd()` except "addr", +--- "nargs" and "nextcmd" which are ignored if provided. All values +--- except for "cmd" are optional. --- @param opts vim.api.keyset.cmd_opts Optional parameters. --- • output: (boolean, default false) Whether to return command --- output. @@ -884,7 +884,7 @@ function vim.api.nvim_command_output(command) end --- --- --- @param name string String: The name of the group ---- @param opts vim.api.keyset.create_augroup Dictionary Parameters +--- @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 @@ -1111,7 +1111,7 @@ function vim.api.nvim_err_write(str) end --- @param str string Message function vim.api.nvim_err_writeln(str) end ---- Evaluates a Vimscript `expression`. Dictionaries and Lists are recursively +--- Evaluates a Vimscript `expression`. Dicts and Lists are recursively --- expanded. --- --- On execution error: fails with Vimscript error, updates v:errmsg. @@ -1165,7 +1165,7 @@ function vim.api.nvim_exec2(src, opts) end --- `autocmd-execute`. --- --- @param event any (String|Array) The event or events to execute ---- @param opts vim.api.keyset.exec_autocmds Dictionary of autocommand options: +--- @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 "*" @@ -1204,8 +1204,8 @@ function vim.api.nvim_feedkeys(keys, mode, escape_ks) end --- Gets the option information for all options. --- ---- The dictionary has the full option names as keys and option metadata ---- dictionaries as detailed at `nvim_get_option_info2()`. +--- The dict has the full option names as keys and option metadata dicts as +--- detailed at `nvim_get_option_info2()`. --- --- @return table function vim.api.nvim_get_all_options_info() end @@ -1231,7 +1231,7 @@ 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 Dictionary with at least one of the following: +--- @param opts vim.api.keyset.get_autocmds Dict with at least one of the following: --- • group (string|integer): the autocommand group name or id to --- match against. --- • event (string|array): event or events to match against @@ -1394,7 +1394,7 @@ function vim.api.nvim_get_option_info(name) end --- Gets the option information for one option from arbitrary buffer or window --- ---- Resulting dictionary has keys: +--- Resulting dict has keys: --- • name: Name of the option (like 'filetype') --- • shortname: Shortened name of the option (like 'ft') --- • type: type of option ("string", "number" or "boolean") -- cgit From d831392b156087ddc38eb75b0260c03f955dd23c Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Tue, 24 Sep 2024 07:14:14 +0800 Subject: feat(paste): unify cancel and error behavior (#30476) Before this PR, the behavior of nvim_paste is: - When vim.paste() returns false, return false to the client, but treat following chunks normally (i.e. rely on the client cancelling the paste as expected). - When vim.paste() throws an error, still return true to the client, but drain the following chunks in the stream without calling vim.paste(). There are two problems with such behavior: - When vim.paste() errors, the client is still supposed to send the remaining chunks of the stream, even though they do nothing. - Having different code paths for two uncommon but similar situations complicates maintenance. This PR makes both the cancel case and the error case return false to the client and drain the remaining chunks of the stream, which, apart from sharing the same code path, is beneficial whether the client checks the return value of nvim_paste or not: - If the client checks the return value, it can avoid sending the following chunks needlessly after an error. - If the client doesn't check the return value, chunks following a cancelled chunk won't be pasted on the server regardless, which leads to less confusing behavior. --- runtime/lua/vim/_meta/api.lua | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index f14606fc99..b53a9ad321 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1816,8 +1816,8 @@ function vim.api.nvim_parse_expression(expr, flags, highlight) end --- --- Errors ('nomodifiable', `vim.paste()` failure, …) are reflected in `err` --- but do not affect the return value (which is strictly decided by ---- `vim.paste()`). On error, subsequent calls are ignored ("drained") until ---- the next paste is initiated (phase 1 or -1). +--- `vim.paste()`). On error or cancel, subsequent calls are ignored +--- ("drained") until the next paste is initiated (phase 1 or -1). --- --- @param data string Multiline input. May be binary (containing NUL bytes). --- @param crlf boolean Also break lines at CR and CRLF. -- cgit From 3f6bc34e663c62bc8899dcdc65bf204b2ccfdaec Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Tue, 24 Sep 2024 04:46:50 -0700 Subject: docs: lua error patterns #30240 Co-authored-by: Mathias Fussenegger Co-authored-by: Ananth Bhaskararaman --- runtime/lua/vim/_meta/api.lua | 36 ++++++++++++++++++++++++++---------- 1 file changed, 26 insertions(+), 10 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index b53a9ad321..a9430078a8 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -744,11 +744,6 @@ function vim.api.nvim_buf_set_option(buffer, name, value) end --- `start_row = end_row = row` and `start_col = end_col = col`. To delete the --- text in a range, use `replacement = {}`. --- ---- Prefer `nvim_buf_set_lines()` if you are only adding or deleting entire ---- lines. ---- ---- Prefer `nvim_put()` if you want to insert text at the cursor position. ---- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param start_row integer First line index --- @param start_col integer Starting column (byte offset) on first line @@ -1484,6 +1479,9 @@ function vim.api.nvim_get_vvar(name) end --- input buffer and the call is non-blocking (input is processed --- asynchronously by the eventloop). --- +--- To input blocks of text, `nvim_paste()` is much faster and should be +--- preferred. +--- --- On execution error: does not fail, but updates v:errmsg. --- --- @param keys string to be typed @@ -1809,17 +1807,34 @@ function vim.api.nvim_parse_cmd(str, opts) end --- @return table function vim.api.nvim_parse_expression(expr, flags, highlight) end ---- Pastes at cursor, in any mode. +--- Pastes at cursor (in any mode), and sets "redo" so dot (`.`) will repeat +--- the input. UIs call this to implement "paste", but it's also intended for +--- use by scripts to input large, dot-repeatable blocks of text (as opposed +--- to `nvim_input()` which is subject to mappings/events and is thus much +--- slower). --- ---- Invokes the `vim.paste` handler, which handles each mode appropriately. ---- Sets redo/undo. Faster than `nvim_input()`. Lines break at LF ("\n"). +--- Invokes the `vim.paste()` handler, which handles each mode appropriately. --- --- Errors ('nomodifiable', `vim.paste()` failure, …) are reflected in `err` --- but do not affect the return value (which is strictly decided by --- `vim.paste()`). On error or cancel, subsequent calls are ignored --- ("drained") until the next paste is initiated (phase 1 or -1). --- ---- @param data string Multiline input. May be binary (containing NUL bytes). +--- Useful in mappings and scripts to insert multiline text. Example: +--- +--- ```vim +--- vim.keymap.set('n', 'x', function() +--- vim.api.nvim_paste([[ +--- line1 +--- line2 +--- line3 +--- ]], false, -1) +--- end, { buffer = true }) +--- ``` +--- +--- +--- @param data string Multiline input. Lines break at LF ("\n"). May be binary +--- (containing NUL bytes). --- @param crlf boolean Also break lines at CR and CRLF. --- @param phase integer -1: paste in a single call (i.e. without streaming). To --- "stream" a paste, call `nvim_paste` sequentially with these @@ -1830,7 +1845,8 @@ function vim.api.nvim_parse_expression(expr, flags, highlight) end --- @return boolean function vim.api.nvim_paste(data, crlf, phase) end ---- Puts text at cursor, in any mode. +--- Puts text at cursor, in any mode. For dot-repeatable input, use +--- `nvim_paste()`. --- --- Compare `:put` and `p` which are always linewise. --- -- cgit From ce7017b850e0f62b3ebe6ea0d7010ba0291624e5 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Wed, 25 Sep 2024 02:34:13 -0700 Subject: docs: render @see, @note items in _meta/api.lua #30494 --- runtime/lua/vim/_meta/api.lua | 100 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 99 insertions(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index a9430078a8..0d4f2c7da0 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -123,6 +123,7 @@ function vim.api.nvim__ns_set(ns_id, opts) end --- --- Instruct Nvim to redraw various components. --- +--- @see `:redraw` --- @param opts vim.api.keyset.redraw Optional parameters. --- • win: Target a specific `window-ID` as described below. --- • buf: Target a specific buffer number as described below. @@ -209,6 +210,8 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- ``` --- --- +--- @see `nvim_buf_detach()` +--- @see `api-buffer-updates-lua` --- @param buffer integer Buffer handle, or 0 for current buffer --- @param send_buffer boolean True if the initial notification should contain the --- whole buffer: first notification will be @@ -305,6 +308,7 @@ function vim.api.nvim_buf_clear_namespace(buffer, ns_id, line_start, line_end) e --- Creates a buffer-local command `user-commands`. --- +--- @see nvim_create_user_command --- @param buffer integer Buffer handle, or 0 for current buffer. --- @param name string --- @param command any @@ -321,6 +325,7 @@ function vim.api.nvim_buf_del_extmark(buffer, ns_id, id) end --- Unmaps a buffer-local `mapping` for the given mode. --- +--- @see `nvim_del_keymap()` --- @param buffer integer Buffer handle, or 0 for current buffer --- @param mode string --- @param lhs string @@ -328,6 +333,12 @@ function vim.api.nvim_buf_del_keymap(buffer, mode, lhs) end --- Deletes a named mark in the buffer. See `mark-motions`. --- +--- Note: +--- • only deletes marks set in the buffer, if the mark is not set in the +--- buffer it will return false. +--- +--- @see `nvim_buf_set_mark()` +--- @see `nvim_del_mark()` --- @param buffer integer Buffer to set the mark on --- @param name string Mark name --- @return boolean @@ -470,6 +481,8 @@ function vim.api.nvim_buf_get_lines(buffer, start, end_, strict_indexing) end --- --- Marks are (1,0)-indexed. `api-indexing` --- +--- @see `nvim_buf_set_mark()` +--- @see `nvim_buf_del_mark()` --- @param buffer integer Buffer handle, or 0 for current buffer --- @param name string Mark name --- @return integer[] @@ -542,6 +555,10 @@ function vim.api.nvim_buf_is_loaded(buffer) end --- Checks if a buffer is valid. --- +--- Note: +--- • Even if a buffer is valid it may have been unloaded. See `api-buffer` +--- for more info about unloaded buffers. +--- --- @param buffer integer Buffer handle, or 0 for current buffer --- @return boolean function vim.api.nvim_buf_is_valid(buffer) end @@ -680,6 +697,7 @@ function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end --- Sets a buffer-local `mapping` for the given mode. --- +--- @see `nvim_set_keymap()` --- @param buffer integer Buffer handle, or 0 for current buffer --- @param mode string --- @param lhs string @@ -699,6 +717,7 @@ function vim.api.nvim_buf_set_keymap(buffer, mode, lhs, rhs, opts) end --- Out-of-bounds indices are clamped to the nearest valid value, unless --- `strict_indexing` is set. --- +--- @see `nvim_buf_set_text()` --- @param buffer integer Buffer handle, or 0 for current buffer --- @param start integer First line index --- @param end_ integer Last line index, exclusive @@ -711,6 +730,11 @@ function vim.api.nvim_buf_set_lines(buffer, start, end_, strict_indexing, replac --- --- Marks are (1,0)-indexed. `api-indexing` --- +--- Note: +--- • Passing 0 as line deletes the mark +--- +--- @see `nvim_buf_del_mark()` +--- @see `nvim_buf_get_mark()` --- @param buffer integer Buffer to set the mark on --- @param name string Mark name --- @param line integer Line number @@ -744,6 +768,12 @@ function vim.api.nvim_buf_set_option(buffer, name, value) end --- `start_row = end_row = row` and `start_col = end_col = col`. To delete the --- text in a range, use `replacement = {}`. --- +--- Note: +--- • Prefer `nvim_buf_set_lines()` (for performance) to add or delete entire +--- lines. +--- • Prefer `nvim_paste()` or `nvim_put()` to insert (instead of replace) +--- text at cursor. +--- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param start_row integer First line index --- @param start_col integer Starting column (byte offset) on first line @@ -839,6 +869,8 @@ function vim.api.nvim_clear_autocmds(opts) end --- --- On execution error: fails with Vimscript error, updates v:errmsg. --- +--- @see `nvim_exec2()` +--- @see `nvim_command()` --- @param cmd vim.api.keyset.cmd Command to execute. Must be a Dict that can contain the same --- values as the return value of `nvim_parse_cmd()` except "addr", --- "nargs" and "nextcmd" which are ignored if provided. All values @@ -863,6 +895,7 @@ function vim.api.nvim_cmd(cmd, opts) end function vim.api.nvim_command(command) end --- @deprecated +--- @see nvim_exec2 --- @param command string --- @return string function vim.api.nvim_command_output(command) end @@ -878,6 +911,7 @@ function vim.api.nvim_command_output(command) end --- ``` --- --- +--- @see `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 @@ -917,6 +951,8 @@ function vim.api.nvim_create_augroup(name, opts) end --- ``` --- --- +--- @see `autocommand` +--- @see `nvim_del_autocmd()` --- @param event any (string|array) Event(s) that will trigger the handler --- (`callback` or `command`). --- @param opts vim.api.keyset.create_autocmd Options dict: @@ -954,6 +990,7 @@ function vim.api.nvim_create_autocmd(event, opts) end --- Creates a new, empty, unnamed buffer. --- +--- @see buf_open_scratch --- @param listed boolean Sets 'buflisted' --- @param scratch boolean Creates a "throwaway" `scratch-buffer` for temporary work --- (always 'nomodified'). Also sets 'nomodeline' on the @@ -1036,6 +1073,8 @@ function vim.api.nvim_create_user_command(name, command, opts) end --- autocommands contained in this group will also be deleted and cleared. --- This group will no longer exist. --- +--- @see `nvim_del_augroup_by_name()` +--- @see `nvim_create_augroup()` --- @param id integer Integer The id of the group. function vim.api.nvim_del_augroup_by_id(id) end @@ -1045,6 +1084,7 @@ function vim.api.nvim_del_augroup_by_id(id) end --- autocommands contained in this group will also be deleted and cleared. --- This group will no longer exist. --- +--- @see `autocmd-groups` --- @param name string String The name of the group. function vim.api.nvim_del_augroup_by_name(name) end @@ -1061,12 +1101,18 @@ function vim.api.nvim_del_current_line() end --- --- To unmap a buffer-local mapping, use `nvim_buf_del_keymap()`. --- +--- @see `nvim_set_keymap()` --- @param mode string --- @param lhs string function vim.api.nvim_del_keymap(mode, lhs) end --- Deletes an uppercase/file named mark. See `mark-motions`. --- +--- Note: +--- • Lowercase name (or other buffer-local mark) is an error. +--- +--- @see `nvim_buf_del_mark()` +--- @see `nvim_get_mark()` --- @param name string Mark name --- @return boolean function vim.api.nvim_del_mark(name) end @@ -1103,6 +1149,7 @@ function vim.api.nvim_err_write(str) end --- Writes a message to the Vim error buffer. Appends "\n", so the buffer is --- flushed (and displayed). --- +--- @see nvim_err_write() --- @param str string Message function vim.api.nvim_err_writeln(str) end @@ -1136,6 +1183,7 @@ function vim.api.nvim_eval(expr) end function vim.api.nvim_eval_statusline(str, opts) end --- @deprecated +--- @see nvim_exec2 --- @param src string --- @param output boolean --- @return string @@ -1149,6 +1197,9 @@ function vim.api.nvim_exec(src, output) end --- --- On execution error: fails with Vimscript error, updates v:errmsg. --- +--- @see `execute()` +--- @see `nvim_command()` +--- @see `nvim_cmd()` --- @param src string Vimscript code --- @param opts vim.api.keyset.exec_opts Optional parameters. --- • output: (boolean, default false) Whether to capture and @@ -1159,6 +1210,7 @@ function vim.api.nvim_exec2(src, opts) end --- Execute all autocommands for {event} that match the corresponding {opts} --- `autocmd-execute`. --- +--- @see `:doautocmd` --- @param event any (String|Array) 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 @@ -1190,6 +1242,8 @@ function vim.api.nvim_exec_autocmds(event, opts) end --- ``` --- --- +--- @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 @@ -1202,6 +1256,7 @@ function vim.api.nvim_feedkeys(keys, mode, escape_ks) end --- The dict has the full option names as keys and option metadata dicts as --- detailed at `nvim_get_option_info2()`. --- +--- @see `nvim_get_commands()` --- @return table function vim.api.nvim_get_all_options_info() end @@ -1272,6 +1327,7 @@ function vim.api.nvim_get_color_map() end --- --- Currently only `user-commands` are supported, not builtin Ex commands. --- +--- @see `nvim_get_all_options_info()` --- @param opts vim.api.keyset.get_commands Optional parameters. Currently only supports {"builtin":false} --- @return table function vim.api.nvim_get_commands(opts) end @@ -1306,6 +1362,10 @@ function vim.api.nvim_get_current_win() end --- Gets all or specific highlight groups in a namespace. --- +--- Note: +--- • When the `link` attribute is defined in the highlight definition map, +--- other attributes will not be taking effect (see `:hi-link`). +--- --- @param ns_id integer Get highlight groups for namespace ns_id --- `nvim_get_namespaces()`. Use 0 to get global highlight groups --- `:highlight`. @@ -1320,12 +1380,14 @@ function vim.api.nvim_get_current_win() end function vim.api.nvim_get_hl(ns_id, opts) end --- @deprecated +--- @see nvim_get_hl_by_name --- @param hl_id integer --- @param rgb boolean --- @return table function vim.api.nvim_get_hl_by_id(hl_id, rgb) end --- @deprecated +--- @see nvim_get_hl_by_id --- @param name string --- @param rgb boolean --- @return table @@ -1361,6 +1423,11 @@ function vim.api.nvim_get_keymap(mode) end --- --- Marks are (1,0)-indexed. `api-indexing` --- +--- Note: +--- • Lowercase name (or other buffer-local mark) is an error. +--- +--- @see `nvim_buf_set_mark()` +--- @see `nvim_del_mark()` --- @param name string Mark name --- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use. --- @return vim.api.keyset.get_mark @@ -1484,6 +1551,12 @@ function vim.api.nvim_get_vvar(name) end --- --- On execution error: does not fail, but updates v:errmsg. --- +--- Note: +--- • `keycodes` like are translated, so "<" is special. To input a +--- literal "<", send . +--- • For mouse events use `nvim_input_mouse()`. The pseudokey form +--- `` is deprecated since `api-level` 6. +--- --- @param keys string to be typed --- @return integer function vim.api.nvim_input(keys) end @@ -1493,6 +1566,13 @@ function vim.api.nvim_input(keys) end --- Non-blocking: does not wait on any result, but queues the event to be --- processed soon by the event loop. --- +--- Note: +--- • Currently this doesn't support "scripting" multiple mouse events by +--- calling it multiple times in a loop: the intermediate mouse positions +--- will be ignored. It should be used to implement real-time mouse input in +--- a GUI. The deprecated pseudokey form (``) of +--- `nvim_input()` has the same limitation. +--- --- @param button string Mouse button: one of "left", "right", "middle", "wheel", --- "move", "x1", "x2". --- @param action string For ordinary buttons, one of "press", "drag", "release". For @@ -1822,7 +1902,7 @@ function vim.api.nvim_parse_expression(expr, flags, highlight) end --- --- Useful in mappings and scripts to insert multiline text. Example: --- ---- ```vim +--- ```lua --- vim.keymap.set('n', 'x', function() --- vim.api.nvim_paste([[ --- line1 @@ -1863,6 +1943,8 @@ function vim.api.nvim_put(lines, type, after, follow) end --- Replaces terminal codes and `keycodes` (, , ...) in a string with --- the internal representation. --- +--- @see replace_termcodes +--- @see cpoptions --- @param str string String to be converted. --- @param from_part boolean Legacy Vim parameter. Usually true. --- @param do_lt boolean Also translate . Ignored if `special` is false. @@ -1973,6 +2055,17 @@ function vim.api.nvim_set_decoration_provider(ns_id, opts) end --- Sets a highlight group. --- +--- Note: +--- • Unlike the `:highlight` command which can update a highlight group, this +--- function completely replaces the definition. For example: +--- `nvim_set_hl(0, 'Visual', {})` will clear the highlight group 'Visual'. +--- • The fg and bg keys also accept the string values `"fg"` or `"bg"` which +--- act as aliases to the corresponding foreground and background values of +--- the Normal group. If the Normal group has not been defined, using these +--- values results in an error. +--- • If `link` is used in combination with other attributes; only the `link` +--- will take effect (see `:hi-link`). +--- --- @param ns_id integer Namespace id for this highlight `nvim_create_namespace()`. --- Use 0 to set a highlight group globally `:highlight`. --- Highlights from non-global namespaces are not active by @@ -2151,6 +2244,8 @@ function vim.api.nvim_tabpage_set_win(tabpage, win) end --- Calls a function with window as temporary current window. --- +--- @see `win_execute()` +--- @see `nvim_buf_call()` --- @param window integer Window handle, or 0 for current window --- @param fun function Function to call inside the window (currently Lua callable --- only) @@ -2191,6 +2286,7 @@ function vim.api.nvim_win_get_config(window) end --- (different windows showing the same buffer have independent cursor --- positions). `api-indexing` --- +--- @see `getcurpos()` --- @param window integer Window handle, or 0 for current window --- @return integer[] function vim.api.nvim_win_get_cursor(window) end @@ -2266,6 +2362,7 @@ function vim.api.nvim_win_set_buf(window, buffer) end --- When reconfiguring a window, absent option keys will not be changed. --- `row`/`col` and `relative` must be reconfigured together. --- +--- @see `nvim_open_win()` --- @param window integer Window handle, or 0 for current window --- @param config vim.api.keyset.win_config Map defining the window configuration, see `nvim_open_win()` function vim.api.nvim_win_set_config(window, config) end @@ -2324,6 +2421,7 @@ function vim.api.nvim_win_set_width(window, width) end --- --- Line indexing is similar to `nvim_buf_get_text()`. --- +--- @see `virtcol()` for text width. --- @param window integer Window handle, or 0 for current window. --- @param opts vim.api.keyset.win_text_height Optional parameters: --- • start_row: Starting line index, 0-based inclusive. When -- cgit From 8801b77ed09876605e42f4a3fddf8c020c14b711 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sat, 5 Oct 2024 08:52:57 -0700 Subject: fix(docs): missing `@returns` desc in _meta/api.lua #30673 --- runtime/lua/vim/_meta/api.lua | 345 ++++++++++++++++++++++++++++++------------ 1 file changed, 251 insertions(+), 94 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 0d4f2c7da0..072f50e1a2 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -27,7 +27,9 @@ function vim.api.nvim__buf_stats(buffer) end --- @param index integer Completion candidate index --- @param opts vim.api.keyset.complete_set Optional parameters. --- • info: (string) info text. ---- @return table +--- @return table # Dict containing these keys: +--- - winid: (number) floating window id +--- - bufnr: (number) buffer id in floating window function vim.api.nvim__complete_set(index, opts) end --- @private @@ -40,7 +42,7 @@ function vim.api.nvim__get_lib_dir() end --- @param pat any[] pattern of files to search for --- @param all boolean whether to return all matches or only the first --- @param opts vim.api.keyset.runtime is_lua: only search Lua subdirs ---- @return string[] +--- @return string[] # list of absolute paths to the found files function vim.api.nvim__get_runtime(pat, all, opts) end --- @private @@ -50,7 +52,7 @@ function vim.api.nvim__get_runtime(pat, all, opts) end --- in plugins. --- --- @param obj any Object to return. ---- @return any +--- @return any # its argument. function vim.api.nvim__id(obj) end --- @private @@ -60,7 +62,7 @@ function vim.api.nvim__id(obj) end --- in plugins. --- --- @param arr any[] Array to return. ---- @return any[] +--- @return any[] # its argument. function vim.api.nvim__id_array(arr) end --- @private @@ -70,7 +72,7 @@ function vim.api.nvim__id_array(arr) end --- in plugins. --- --- @param dct table Dict to return. ---- @return table +--- @return table # its argument. function vim.api.nvim__id_dict(dct) end --- @private @@ -80,7 +82,7 @@ function vim.api.nvim__id_dict(dct) end --- in plugins. --- --- @param flt number Value to return. ---- @return number +--- @return number # its argument. function vim.api.nvim__id_float(flt) end --- @private @@ -105,7 +107,7 @@ function vim.api.nvim__invalidate_glyph_cache() end --- Get the properties for namespace --- --- @param ns_id integer Namespace ---- @return vim.api.keyset.ns_opts +--- @return vim.api.keyset.ns_opts # Map defining the namespace properties, see |nvim__ns_set()| function vim.api.nvim__ns_get(ns_id) end --- @private @@ -156,7 +158,7 @@ function vim.api.nvim__screenshot(path) end --- @private --- Gets internal stats. --- ---- @return table +--- @return table # Map of various internal stats. function vim.api.nvim__stats() end --- @private @@ -192,7 +194,7 @@ function vim.api.nvim__unpack(str) end --- @param col_start integer Start of (byte-indexed) column range to highlight --- @param col_end integer End of (byte-indexed) column range to highlight, or -1 to --- highlight to end of line ---- @return integer +--- @return integer # The ns_id that was used function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start, col_end) end --- Activates buffer-update events on a channel, or as Lua callbacks. @@ -265,7 +267,8 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- region, as args to `on_lines`. --- • preview: also attach to command preview (i.e. 'inccommand') --- events. ---- @return boolean +--- @return boolean # False if attach failed (invalid parameter, or buffer isn't loaded); +--- otherwise True. TODO: LUA_API_NO_EVAL function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end --- Call a function with buffer as temporary current buffer. @@ -283,7 +286,7 @@ function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end --- @param buffer integer Buffer handle, or 0 for current buffer --- @param fun function Function to call inside the buffer (currently Lua callable --- only) ---- @return any +--- @return any # Return value of function. function vim.api.nvim_buf_call(buffer, fun) end --- @deprecated @@ -320,7 +323,7 @@ function vim.api.nvim_buf_create_user_command(buffer, name, command, opts) end --- @param buffer integer Buffer handle, or 0 for current buffer --- @param ns_id integer Namespace id from `nvim_create_namespace()` --- @param id integer Extmark id ---- @return boolean +--- @return boolean # true if the extmark was found, else false function vim.api.nvim_buf_del_extmark(buffer, ns_id, id) end --- Unmaps a buffer-local `mapping` for the given mode. @@ -341,7 +344,7 @@ function vim.api.nvim_buf_del_keymap(buffer, mode, lhs) end --- @see `nvim_del_mark()` --- @param buffer integer Buffer to set the mark on --- @param name string Mark name ---- @return boolean +--- @return boolean # true if the mark was deleted, else false. function vim.api.nvim_buf_del_mark(buffer, name) end --- Delete a buffer-local user-defined command. @@ -370,14 +373,14 @@ function vim.api.nvim_buf_delete(buffer, opts) end --- Gets a changed tick of a buffer --- --- @param buffer integer Buffer handle, or 0 for current buffer ---- @return integer +--- @return integer # `b:changedtick` value. function vim.api.nvim_buf_get_changedtick(buffer) end --- Gets a map of buffer-local `user-commands`. --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param opts vim.api.keyset.get_commands Optional parameters. Currently not used. ---- @return table +--- @return table # Map of maps describing commands. function vim.api.nvim_buf_get_commands(buffer, opts) end --- Gets the position (0-indexed) of an `extmark`. @@ -389,7 +392,8 @@ function vim.api.nvim_buf_get_commands(buffer, opts) end --- • details: Whether to include the details dict --- • hl_name: Whether to include highlight group name instead of --- id, true if omitted ---- @return vim.api.keyset.get_extmark_item_by_id +--- @return vim.api.keyset.get_extmark_item_by_id # 0-indexed (row, col) tuple or empty list () if extmark id was +--- absent function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- Gets `extmarks` in "traversal order" from a `charwise` region defined by @@ -449,14 +453,15 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- their start position is less than `start` --- • type: Filter marks by type: "highlight", "sign", "virt_text" --- and "virt_lines" ---- @return vim.api.keyset.get_extmark_item[] +--- @return vim.api.keyset.get_extmark_item[] # List of `[extmark_id, row, col]` tuples in "traversal order". function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end --- Gets a list of buffer-local `mapping` definitions. --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param mode string Mode short-name ("n", "i", "v", ...) ---- @return vim.api.keyset.keymap[] +--- @return vim.api.keyset.keymap[] # Array of |maparg()|-like dictionaries describing mappings. +--- The "buffer" key holds the associated buffer handle. function vim.api.nvim_buf_get_keymap(buffer, mode) end --- Gets a line-range from the buffer. @@ -472,7 +477,7 @@ function vim.api.nvim_buf_get_keymap(buffer, mode) end --- @param start integer First line index --- @param end_ integer Last line index, exclusive --- @param strict_indexing boolean Whether out-of-bounds should be an error. ---- @return string[] +--- @return string[] # Array of lines, or empty array for unloaded buffer. function vim.api.nvim_buf_get_lines(buffer, start, end_, strict_indexing) end --- Returns a `(row,col)` tuple representing the position of the named mark. @@ -485,13 +490,14 @@ function vim.api.nvim_buf_get_lines(buffer, start, end_, strict_indexing) end --- @see `nvim_buf_del_mark()` --- @param buffer integer Buffer handle, or 0 for current buffer --- @param name string Mark name ---- @return integer[] +--- @return integer[] # (row, col) tuple, (0, 0) if the mark is not set, or is an +--- uppercase/file mark set in another buffer. function vim.api.nvim_buf_get_mark(buffer, name) end --- Gets the full file name for the buffer --- --- @param buffer integer Buffer handle, or 0 for current buffer ---- @return string +--- @return string # Buffer name function vim.api.nvim_buf_get_name(buffer) end --- @deprecated @@ -511,7 +517,7 @@ function vim.api.nvim_buf_get_number(buffer) end --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param index integer Line index ---- @return integer +--- @return integer # Integer byte offset, or -1 for unloaded buffer. function vim.api.nvim_buf_get_offset(buffer, index) end --- @deprecated @@ -536,21 +542,21 @@ function vim.api.nvim_buf_get_option(buffer, name) end --- @param end_row integer Last line index, inclusive --- @param end_col integer Ending column (byte offset) on last line, exclusive --- @param opts vim.api.keyset.empty Optional parameters. Currently unused. ---- @return string[] +--- @return string[] # Array of lines, or empty array for unloaded buffer. function vim.api.nvim_buf_get_text(buffer, start_row, start_col, end_row, end_col, opts) end --- Gets a buffer-scoped (b:) variable. --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param name string Variable name ---- @return any +--- @return any # Variable value function vim.api.nvim_buf_get_var(buffer, name) end --- Checks if a buffer is valid and loaded. See `api-buffer` for more info --- about unloaded buffers. --- --- @param buffer integer Buffer handle, or 0 for current buffer ---- @return boolean +--- @return boolean # true if the buffer is valid and loaded, false otherwise. function vim.api.nvim_buf_is_loaded(buffer) end --- Checks if a buffer is valid. @@ -560,13 +566,13 @@ function vim.api.nvim_buf_is_loaded(buffer) end --- for more info about unloaded buffers. --- --- @param buffer integer Buffer handle, or 0 for current buffer ---- @return boolean +--- @return boolean # true if the buffer is valid, false otherwise. function vim.api.nvim_buf_is_valid(buffer) end --- Returns the number of lines in the given buffer. --- --- @param buffer integer Buffer handle, or 0 for current buffer ---- @return integer +--- @return integer # Line count, or 0 for unloaded buffer. |api-buffer| function vim.api.nvim_buf_line_count(buffer) end --- Creates or updates an `extmark`. @@ -692,7 +698,7 @@ function vim.api.nvim_buf_line_count(buffer) end --- • url: A URL to associate with this extmark. In the TUI, the --- OSC 8 control sequence is used to generate a clickable --- hyperlink to this URL. ---- @return integer +--- @return integer # Id of the created/updated extmark function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end --- Sets a buffer-local `mapping` for the given mode. @@ -740,7 +746,7 @@ function vim.api.nvim_buf_set_lines(buffer, start, end_, strict_indexing, replac --- @param line integer Line number --- @param col integer Column/row number --- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use. ---- @return boolean +--- @return boolean # true if the mark was set, else false. function vim.api.nvim_buf_set_mark(buffer, name, line, col, opts) end --- Sets the full file name for a buffer, like `:file_f` @@ -805,7 +811,7 @@ function vim.api.nvim_buf_set_virtual_text(buffer, src_id, line, chunks, opts) e --- @param dict any Dict, or String evaluating to a Vimscript `self` dict --- @param fn string Name of the function defined on the Vimscript dict --- @param args any[] Function arguments packed in an Array ---- @return any +--- @return any # Result of the function call function vim.api.nvim_call_dict_function(dict, fn, args) end --- Calls a Vimscript function with the given arguments. @@ -814,7 +820,7 @@ function vim.api.nvim_call_dict_function(dict, fn, args) end --- --- @param fn string Function to call --- @param args any[] Function arguments packed in an Array ---- @return any +--- @return any # Result of the function call function vim.api.nvim_call_function(fn, args) end --- Send data to channel `id`. For a job, it writes it to the stdin of the @@ -878,7 +884,7 @@ function vim.api.nvim_clear_autocmds(opts) end --- @param opts vim.api.keyset.cmd_opts Optional parameters. --- • output: (boolean, default false) Whether to return command --- output. ---- @return string +--- @return string # Command output (non-error, non-shell |:!|) if `output` is true, else empty string. function vim.api.nvim_cmd(cmd, opts) end --- Executes an Ex command. @@ -916,7 +922,7 @@ function vim.api.nvim_command_output(command) end --- @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 +--- @return integer # Integer id of the created group. function vim.api.nvim_create_augroup(name, opts) end --- Creates an `autocommand` event handler, defined by `callback` (Lua @@ -985,7 +991,7 @@ function vim.api.nvim_create_augroup(name, opts) end --- autocommand only once `autocmd-once`. --- • nested (boolean) optional: defaults to false. Run nested --- autocommands `autocmd-nested`. ---- @return integer +--- @return integer # Autocommand id (number) function vim.api.nvim_create_autocmd(event, opts) end --- Creates a new, empty, unnamed buffer. @@ -995,7 +1001,7 @@ function vim.api.nvim_create_autocmd(event, opts) end --- @param scratch boolean Creates a "throwaway" `scratch-buffer` for temporary work --- (always 'nomodified'). Also sets 'nomodeline' on the --- buffer. ---- @return integer +--- @return integer # Buffer handle, or 0 on error function vim.api.nvim_create_buf(listed, scratch) end --- Creates a new namespace or gets an existing one. *namespace* @@ -1008,7 +1014,7 @@ function vim.api.nvim_create_buf(listed, scratch) end --- new, anonymous namespace is created. --- --- @param name string Namespace name or empty string ---- @return integer +--- @return integer # Namespace id function vim.api.nvim_create_namespace(name) end --- Creates a global `user-commands` command. @@ -1114,7 +1120,7 @@ function vim.api.nvim_del_keymap(mode, lhs) end --- @see `nvim_buf_del_mark()` --- @see `nvim_get_mark()` --- @param name string Mark name ---- @return boolean +--- @return boolean # true if the mark was deleted, else false. function vim.api.nvim_del_mark(name) end --- Delete a user-defined command. @@ -1159,7 +1165,7 @@ function vim.api.nvim_err_writeln(str) end --- On execution error: fails with Vimscript error, updates v:errmsg. --- --- @param expr string Vimscript expression string ---- @return any +--- @return any # Evaluation result or expanded object function vim.api.nvim_eval(expr) end --- Evaluates statusline string. @@ -1179,7 +1185,14 @@ function vim.api.nvim_eval(expr) end --- exclusive with {use_winbar}. --- • use_statuscol_lnum: (number) Evaluate statuscolumn for this --- line number instead of statusline. ---- @return table +--- @return table # Dict containing statusline information, with these keys: +--- - str: (string) Characters that will be displayed on the statusline. +--- - width: (number) Display width of the statusline. +--- - highlights: Array containing highlight information of the statusline. Only included when +--- the "highlights" key in {opts} is true. Each element of the array is a +--- |Dict| with these keys: +--- - start: (number) Byte index (0-based) of first character that uses the highlight. +--- - group: (string) Name of highlight group. function vim.api.nvim_eval_statusline(str, opts) end --- @deprecated @@ -1204,7 +1217,8 @@ function vim.api.nvim_exec(src, output) end --- @param opts vim.api.keyset.exec_opts Optional parameters. --- • output: (boolean, default false) Whether to capture and --- return all (non-error, non-shell `:!`) output. ---- @return table +--- @return table # Dict containing information about execution, with these keys: +--- - 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} @@ -1257,7 +1271,7 @@ function vim.api.nvim_feedkeys(keys, mode, escape_ks) end --- detailed at `nvim_get_option_info2()`. --- --- @see `nvim_get_commands()` ---- @return table +--- @return table # dict of all options function vim.api.nvim_get_all_options_info() end --- Get all autocommands that match the corresponding {opts}. @@ -1291,13 +1305,44 @@ function vim.api.nvim_get_all_options_info() end --- • buffer: Buffer number or list of buffer numbers for buffer --- local autocommands `autocmd-buflocal`. Cannot be used with --- {pattern} ---- @return vim.api.keyset.get_autocmds.ret[] +--- @return vim.api.keyset.get_autocmds.ret[] # Array of autocommands matching the criteria, with each item +--- containing the following fields: +--- - id (number): the autocommand id (only when defined with the API). +--- - group (integer): the autocommand group id. +--- - group_name (string): the autocommand group name. +--- - desc (string): the autocommand description. +--- - event (string): the autocommand event. +--- - 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. +--- - once (boolean): whether the autocommand is only run once. +--- - pattern (string): the autocommand pattern. +--- If the autocommand is buffer local |autocmd-buffer-local|: +--- - buflocal (boolean): true if the autocommand is buffer local. +--- - buffer (number): the buffer number. function vim.api.nvim_get_autocmds(opts) end --- Gets information about a channel. --- --- @param chan integer channel_id, or 0 for current channel ---- @return table +--- @return table # Channel info dict with these keys: +--- - "id" Channel id. +--- - "argv" (optional) Job arguments list. +--- - "stream" Stream underlying the channel. +--- - "stdio" stdin and stdout of this Nvim instance +--- - "stderr" stderr of this Nvim instance +--- - "socket" TCP/IP socket or named pipe +--- - "job" Job with communication over its stdio. +--- - "mode" How data received on the channel is interpreted. +--- - "bytes" Send and receive raw bytes. +--- - "terminal" |terminal| instance interprets ASCII sequences. +--- - "rpc" |RPC| communication on the channel is active. +--- - "pty" (optional) Name of pseudoterminal. On a POSIX system this is a device path like +--- "/dev/pts/1". If unknown, the key will still be present if a pty is used (e.g. +--- for conpty on Windows). +--- - "buffer" (optional) Buffer connected to |terminal| instance. +--- - "client" (optional) Info about the peer (client on the other end of the RPC channel), +--- which it provided via |nvim_set_client_info()|. function vim.api.nvim_get_chan_info(chan) end --- Returns the 24-bit RGB value of a `nvim_get_color_map()` color name or @@ -1312,7 +1357,7 @@ function vim.api.nvim_get_chan_info(chan) end --- --- --- @param name string Color name or "#rrggbb" string ---- @return integer +--- @return integer # 24-bit RGB value, or -1 for invalid argument. function vim.api.nvim_get_color_by_name(name) end --- Returns a map of color names and RGB values. @@ -1320,7 +1365,7 @@ function vim.api.nvim_get_color_by_name(name) end --- Keys are color names (e.g. "Aqua") and values are 24-bit RGB color values --- (e.g. 65535). --- ---- @return table +--- @return table # Map of color names and RGB values. function vim.api.nvim_get_color_map() end --- Gets a map of global (non-buffer-local) Ex commands. @@ -1329,7 +1374,7 @@ function vim.api.nvim_get_color_map() end --- --- @see `nvim_get_all_options_info()` --- @param opts vim.api.keyset.get_commands Optional parameters. Currently only supports {"builtin":false} ---- @return table +--- @return table # Map of maps describing commands. function vim.api.nvim_get_commands(opts) end --- Gets a map of the current editor state. @@ -1337,27 +1382,27 @@ function vim.api.nvim_get_commands(opts) end --- @param opts vim.api.keyset.context Optional parameters. --- • types: List of `context-types` ("regs", "jumps", "bufs", --- "gvars", …) to gather, or empty for "all". ---- @return table +--- @return table # map of global |context|. function vim.api.nvim_get_context(opts) end --- Gets the current buffer. --- ---- @return integer +--- @return integer # Buffer handle function vim.api.nvim_get_current_buf() end --- Gets the current line. --- ---- @return string +--- @return string # Current line string function vim.api.nvim_get_current_line() end --- Gets the current tabpage. --- ---- @return integer +--- @return integer # Tabpage handle function vim.api.nvim_get_current_tabpage() end --- Gets the current window. --- ---- @return integer +--- @return integer # Window handle function vim.api.nvim_get_current_win() end --- Gets all or specific highlight groups in a namespace. @@ -1376,7 +1421,8 @@ function vim.api.nvim_get_current_win() end --- of effective definition `:hi-link`. --- • create: (boolean, default true) When highlight group doesn't --- exist create it. ---- @return vim.api.keyset.get_hl_info +--- @return vim.api.keyset.get_hl_info # Highlight groups as a map from group name to a highlight definition map as in |nvim_set_hl()|, +--- or only a single highlight definition map if requested by name or id. function vim.api.nvim_get_hl(ns_id, opts) end --- @