diff options
| -rw-r--r-- | runtime/doc/api.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/news.txt | 3 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/api.lua | 100 | ||||
| -rwxr-xr-x | scripts/gen_eval_files.lua | 33 | ||||
| -rw-r--r-- | src/nvim/api/vim.c | 2 | ||||
| -rw-r--r-- | src/nvim/eval.lua | 2 |
6 files changed, 139 insertions, 3 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 828b3e5ec1..dee0324a5b 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -1164,7 +1164,7 @@ nvim_paste({data}, {crlf}, {phase}) *nvim_paste()* `vim.paste()`). On error or cancel, subsequent calls are ignored ("drained") until the next paste is initiated (phase 1 or -1). - Useful in mappings and scripts to insert multiline text. Example: >vim + Useful in mappings and scripts to insert multiline text. Example: >lua vim.keymap.set('n', 'x', function() vim.api.nvim_paste([[ line1 diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 685be37bce..a359d57a99 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -137,6 +137,9 @@ DEFAULTS EDITOR +• Improved |paste| handling for redo (dot-repeat) and macros (|recording|): + • Redoing a large paste is significantly faster and ignores 'autoindent'. + • Replaying a macro with |@| also replays pasted text. • On Windows, filename arguments on the command-line prefixed with "~\" or "~/" are now expanded to the user's profile directory, not a relative path to a literal "~" directory. 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 diff --git a/scripts/gen_eval_files.lua b/scripts/gen_eval_files.lua index 35af84ae28..6c97893a4a 100755 --- a/scripts/gen_eval_files.lua +++ b/scripts/gen_eval_files.lua @@ -245,6 +245,16 @@ local function get_api_meta() for _, fun in pairs(functions) do local deprecated = fun.deprecated_since ~= nil + local notes = {} --- @type string[] + for _, note in ipairs(fun.notes or {}) do + notes[#notes + 1] = note.desc + end + + local sees = {} --- @type string[] + for _, see in ipairs(fun.see or {}) do + sees[#sees + 1] = see.desc + end + local params = {} --- @type [string,string][] for _, p in ipairs(fun.params) do params[#params + 1] = { @@ -258,6 +268,8 @@ local function get_api_meta() signature = 'NA', name = fun.name, params = params, + notes = notes, + see = sees, returns = api_type(fun.returns[1].type), deprecated = deprecated, } @@ -315,6 +327,26 @@ local function render_api_meta(_f, fun, write) end end + -- LuaLS doesn't support @note. Render @note items as a markdown list. + if fun.notes and #fun.notes > 0 then + write('--- Note:') + for _, note in ipairs(fun.notes) do + -- XXX: abuse md_to_vimdoc() to force-fit the markdown list. Need norm_md()? + note = text_utils.md_to_vimdoc(' - ' .. note, 0, 0, 74) + for _, l in ipairs(split(vim.trim(norm_text(note)))) do + write('--- ' .. l:gsub('\n*$', '')) + end + end + write('---') + end + + for _, see in ipairs(fun.see or {}) do + see = text_utils.md_to_vimdoc('@see ' .. see, 0, 0, 74) + for _, l in ipairs(split(vim.trim(norm_text(see)))) do + write('--- ' .. l:gsub([[\s*$]], '')) + end + end + local param_names = {} --- @type string[] local params = process_params(fun.params) for _, p in ipairs(params) do @@ -336,6 +368,7 @@ local function render_api_meta(_f, fun, write) write('--- @param ' .. p[1] .. ' ' .. p[2]) end end + if fun.returns ~= '' then local ret_desc = fun.returns_desc and ' : ' .. fun.returns_desc or '' ret_desc = text_utils.md_to_vimdoc(ret_desc, 0, 0, 74) diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index d18cfaccd0..8c88a19147 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -1226,7 +1226,7 @@ void nvim_set_current_tabpage(Tabpage tabpage, Error *err) /// /// Useful in mappings and scripts to insert multiline text. Example: /// -/// ```vim +/// ```lua /// vim.keymap.set('n', 'x', function() /// vim.api.nvim_paste([[ /// line1 diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua index 25c1fec1e4..2a3327b37b 100644 --- a/src/nvim/eval.lua +++ b/src/nvim/eval.lua @@ -20,6 +20,8 @@ --- @field signature? string --- @field desc? string --- @field params [string, string, string][] +--- @field notes? string[] +--- @field see? string[] --- @field lua? false Do not render type information --- @field tags? string[] Extra tags --- @field data? string Used by gen_eval.lua |