kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-23 12:45:17 -07:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Justin M. Keyes 2024-09-25 02:34:13 -07:00 committed by GitHub
parent 6c77e840ae
commit ce7017b850
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
6 changed files with 139 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
runtime/doc/api.txt
View File

@ -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

3
runtime/doc/news.txt
View File

@ -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.

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

@ -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

33
scripts/gen_eval_files.lua
View File

@ -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)

2
src/nvim/api/vim.c
View File

@ -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

2
src/nvim/eval.lua
View File

@ -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