docs: render @see, @note items in _meta/api.lua #30494

1 files changed, 99 insertions, 1 deletions

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<string,any>
 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<string,any>
 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<string,any>
 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<string,any>
@@ -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 <CR> are translated, so "<" is special. To input a
+---   literal "<", send <LT>.
+--- • For mouse events use `nvim_input_mouse()`. The pseudokey form
+---   `<LeftMouse><col,row>` 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 (`<LeftMouse><col,row>`) 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` (<CR>, <Esc>, ...) 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 <lt>. 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