From 041a939eeb21dd8a62c479f12cc9334d3d30a832 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 16 Mar 2025 14:13:02 +0100 Subject: docs(api): rename "handle" => "id" --- runtime/lua/vim/_meta/api.lua | 88 ++++++++++++++++++++++--------------------- 1 file changed, 45 insertions(+), 43 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 63a7bcc37d..69cb424254 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -176,7 +176,7 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- --- @see vim.api.nvim_buf_detach --- @see `:help api-buffer-updates-lua` ---- @param buffer integer Buffer handle, or 0 for current buffer +--- @param buffer integer Buffer id, or 0 for current buffer --- @param send_buffer boolean True if the initial notification should contain the --- whole buffer: first notification will be `nvim_buf_lines_event`. --- Else the first notification will be `nvim_buf_changedtick_event`. @@ -185,7 +185,7 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- - on_lines: Lua callback invoked on change. --- Return a truthy value (not `false` or `nil`) to detach. Args: --- - the string "lines" ---- - buffer handle +--- - buffer id --- - b:changedtick --- - first line that changed (zero-indexed) --- - last line that was changed @@ -198,7 +198,7 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- change compared to on_lines. --- Return a truthy value (not `false` or `nil`) to detach. Args: --- - the string "bytes" ---- - buffer handle +--- - buffer id --- - b:changedtick --- - start row of the changed text (zero-indexed) --- - start column of the changed text @@ -215,15 +215,15 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- - on_changedtick: Lua callback invoked on changedtick --- increment without text change. Args: --- - the string "changedtick" ---- - buffer handle +--- - buffer id --- - b:changedtick --- - on_detach: Lua callback invoked on detach. Args: --- - the string "detach" ---- - buffer handle +--- - buffer id --- - on_reload: Lua callback invoked on reload. The entire buffer --- content should be considered changed. Args: --- - the string "reload" ---- - buffer handle +--- - buffer id --- - utf_sizes: include UTF-32 and UTF-16 size of the replaced --- region, as args to `on_lines`. --- - preview: also attach to command preview (i.e. 'inccommand') @@ -244,7 +244,7 @@ function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end --- This is useful e.g. to call Vimscript functions that only work with the --- current buffer/window currently, like `jobstart(…, {'term': v:true})`. --- ---- @param buffer integer Buffer handle, or 0 for current buffer +--- @param buffer integer Buffer id, or 0 for current buffer --- @param fun function Function to call inside the buffer (currently Lua callable --- only) --- @return any # Return value of function. @@ -263,7 +263,7 @@ function vim.api.nvim_buf_clear_highlight(buffer, ns_id, line_start, line_end) e --- Lines are 0-indexed. `api-indexing` To clear the namespace in the entire --- buffer, specify line_start=0 and line_end=-1. --- ---- @param buffer integer Buffer handle, or 0 for current buffer +--- @param buffer integer Buffer id, or 0 for current buffer --- @param ns_id integer Namespace to clear, or -1 to clear all namespaces. --- @param line_start integer Start of range of lines to clear --- @param line_end integer End of range of lines to clear (exclusive) or -1 to clear @@ -273,7 +273,7 @@ function vim.api.nvim_buf_clear_namespace(buffer, ns_id, line_start, line_end) e --- Creates a buffer-local command `user-commands`. --- --- @see vim.api.nvim_create_user_command ---- @param buffer integer Buffer handle, or 0 for current buffer. +--- @param buffer integer Buffer id, or 0 for current buffer. --- @param name string --- @param command any --- @param opts vim.api.keyset.user_command @@ -281,7 +281,7 @@ function vim.api.nvim_buf_create_user_command(buffer, name, command, opts) end --- Removes an `extmark`. --- ---- @param buffer integer Buffer handle, or 0 for current buffer +--- @param buffer integer Buffer id, or 0 for current buffer --- @param ns_id integer Namespace id from `nvim_create_namespace()` --- @param id integer Extmark id --- @return boolean # true if the extmark was found, else false @@ -291,7 +291,7 @@ function vim.api.nvim_buf_del_extmark(buffer, ns_id, id) end --- --- --- @see vim.api.nvim_del_keymap ---- @param buffer integer Buffer handle, or 0 for current buffer +--- @param buffer integer Buffer id, or 0 for current buffer --- @param mode string --- @param lhs string function vim.api.nvim_buf_del_keymap(buffer, mode, lhs) end @@ -314,19 +314,19 @@ function vim.api.nvim_buf_del_mark(buffer, name) end --- Only commands created with `:command-buffer` or --- `nvim_buf_create_user_command()` can be deleted with this function. --- ---- @param buffer integer Buffer handle, or 0 for current buffer. +--- @param buffer integer Buffer id, or 0 for current buffer. --- @param name string Name of the command to delete. function vim.api.nvim_buf_del_user_command(buffer, name) end --- Removes a buffer-scoped (b:) variable --- ---- @param buffer integer Buffer handle, or 0 for current buffer +--- @param buffer integer Buffer id, or 0 for current buffer --- @param name string Variable name function vim.api.nvim_buf_del_var(buffer, name) end --- Deletes the buffer. See `:bwipeout` --- ---- @param buffer integer Buffer handle, or 0 for current buffer +--- @param buffer integer Buffer id, or 0 for current buffer --- @param opts vim.api.keyset.buf_delete Optional parameters. Keys: --- - force: Force deletion and ignore unsaved changes. --- - unload: Unloaded only, do not delete. See `:bunload` @@ -334,20 +334,20 @@ 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 +--- @param buffer integer Buffer id, or 0 for current buffer --- @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 buffer integer Buffer id, or 0 for current buffer --- @param opts vim.api.keyset.get_commands Optional parameters. Currently not used. --- @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`. --- ---- @param buffer integer Buffer handle, or 0 for current buffer +--- @param buffer integer Buffer id, or 0 for current buffer --- @param ns_id integer Namespace id from `nvim_create_namespace()` --- @param id integer Extmark id --- @param opts vim.api.keyset.get_extmark Optional parameters. Keys: @@ -397,7 +397,7 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- vim.print(ms) --- ``` --- ---- @param buffer integer Buffer handle, or 0 for current buffer +--- @param buffer integer Buffer id, or 0 for current buffer --- @param ns_id integer Namespace id from `nvim_create_namespace()` or -1 for all namespaces --- @param start any Start of range: a 0-indexed (row, col) or valid extmark id --- (whose position defines the bound). `api-indexing` @@ -415,10 +415,10 @@ 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 buffer integer Buffer id, or 0 for current buffer --- @param mode string Mode short-name ("n", "i", "v", ...) --- @return vim.api.keyset.get_keymap[] # Array of |maparg()|-like dictionaries describing mappings. ---- The "buffer" key holds the associated buffer handle. +--- The "buffer" key holds the associated buffer id. function vim.api.nvim_buf_get_keymap(buffer, mode) end --- Gets a line-range from the buffer. @@ -430,7 +430,9 @@ function vim.api.nvim_buf_get_keymap(buffer, mode) end --- Out-of-bounds indices are clamped to the nearest valid value, unless --- `strict_indexing` is set. --- ---- @param buffer integer Buffer handle, or 0 for current buffer +--- +--- @see vim.api.nvim_buf_get_text +--- @param buffer integer Buffer id, or 0 for current buffer --- @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. @@ -445,7 +447,7 @@ function vim.api.nvim_buf_get_lines(buffer, start, end_, strict_indexing) end --- --- @see vim.api.nvim_buf_set_mark --- @see vim.api.nvim_buf_del_mark ---- @param buffer integer Buffer handle, or 0 for current buffer +--- @param buffer integer Buffer id, or 0 for current buffer --- @param name string Mark name --- @return integer[] # (row, col) tuple, (0, 0) if the mark is not set, or is an --- uppercase/file mark set in another buffer. @@ -453,7 +455,7 @@ 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 +--- @param buffer integer Buffer id, or 0 for current buffer --- @return string # Buffer name function vim.api.nvim_buf_get_name(buffer) end @@ -472,7 +474,7 @@ function vim.api.nvim_buf_get_number(buffer) end --- Unlike `line2byte()`, throws error for out-of-bounds indexing. --- Returns -1 for unloaded buffer. --- ---- @param buffer integer Buffer handle, or 0 for current buffer +--- @param buffer integer Buffer id, or 0 for current buffer --- @param index integer Line index --- @return integer # Integer byte offset, or -1 for unloaded buffer. function vim.api.nvim_buf_get_offset(buffer, index) end @@ -493,7 +495,7 @@ function vim.api.nvim_buf_get_option(buffer, name) end --- --- Prefer `nvim_buf_get_lines()` when retrieving entire lines. --- ---- @param buffer integer Buffer handle, or 0 for current buffer +--- @param buffer integer Buffer id, or 0 for current buffer --- @param start_row integer First line index --- @param start_col integer Starting column (byte offset) on first line --- @param end_row integer Last line index, inclusive @@ -504,7 +506,7 @@ function vim.api.nvim_buf_get_text(buffer, start_row, start_col, end_row, end_co --- Gets a buffer-scoped (b:) variable. --- ---- @param buffer integer Buffer handle, or 0 for current buffer +--- @param buffer integer Buffer id, or 0 for current buffer --- @param name string Variable name --- @return any # Variable value function vim.api.nvim_buf_get_var(buffer, name) end @@ -512,7 +514,7 @@ 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 +--- @param buffer integer Buffer id, or 0 for current buffer --- @return boolean # true if the buffer is valid and loaded, false otherwise. function vim.api.nvim_buf_is_loaded(buffer) end @@ -523,13 +525,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 +--- @param buffer integer Buffer id, or 0 for current buffer --- @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 +--- @param buffer integer Buffer id, or 0 for current buffer --- @return integer # Line count, or 0 for unloaded buffer. |api-buffer| function vim.api.nvim_buf_line_count(buffer) end @@ -549,7 +551,7 @@ function vim.api.nvim_buf_line_count(buffer) end --- An earlier end position is not an error, but then it behaves like an empty --- range (no highlighting). --- ---- @param buffer integer Buffer handle, or 0 for current buffer +--- @param buffer integer Buffer id, or 0 for current buffer --- @param ns_id integer Namespace id from `nvim_create_namespace()` --- @param line integer Line where to place the mark, 0-based. `api-indexing` --- @param col integer Column where to place the mark, 0-based. `api-indexing` @@ -685,7 +687,7 @@ function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end --- --- --- @see vim.api.nvim_set_keymap ---- @param buffer integer Buffer handle, or 0 for current buffer +--- @param buffer integer Buffer id, or 0 for current buffer --- @param mode string --- @param lhs string --- @param rhs string @@ -706,7 +708,7 @@ function vim.api.nvim_buf_set_keymap(buffer, mode, lhs, rhs, opts) end --- --- --- @see vim.api.nvim_buf_set_text ---- @param buffer integer Buffer handle, or 0 for current buffer +--- @param buffer integer Buffer id, or 0 for current buffer --- @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. @@ -734,7 +736,7 @@ function vim.api.nvim_buf_set_mark(buffer, name, line, col, opts) end --- Sets the full file name for a buffer, like `:file_f` --- ---- @param buffer integer Buffer handle, or 0 for current buffer +--- @param buffer integer Buffer id, or 0 for current buffer --- @param name string Buffer name function vim.api.nvim_buf_set_name(buffer, name) end @@ -762,7 +764,7 @@ function vim.api.nvim_buf_set_option(buffer, name, value) end --- 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 buffer integer Buffer id, or 0 for current buffer --- @param start_row integer First line index --- @param start_col integer Starting column (byte offset) on first line --- @param end_row integer Last line index, inclusive @@ -772,7 +774,7 @@ function vim.api.nvim_buf_set_text(buffer, start_row, start_col, end_row, end_co --- Sets a buffer-scoped (b:) variable --- ---- @param buffer integer Buffer handle, or 0 for current buffer +--- @param buffer integer Buffer id, or 0 for current buffer --- @param name string Variable name --- @param value any Variable value function vim.api.nvim_buf_set_var(buffer, name, value) end @@ -964,7 +966,7 @@ function vim.api.nvim_create_autocmd(event, opts) end --- @param listed boolean Sets 'buflisted' --- @param scratch boolean Creates a "throwaway" `scratch-buffer` for temporary work --- (always 'nomodified'). Also sets 'nomodeline' on the buffer. ---- @return integer # Buffer handle, or 0 on error +--- @return integer # Buffer id, or 0 on error --- function vim.api.nvim_create_buf(listed, scratch) end @@ -1331,7 +1333,7 @@ function vim.api.nvim_get_context(opts) end --- Gets the current buffer. --- ---- @return integer # Buffer handle +--- @return integer # Buffer id function vim.api.nvim_get_current_buf() end --- Gets the current line. @@ -1580,12 +1582,12 @@ function vim.api.nvim_input(keys) end --- @param col integer Mouse column-position (zero-based, like redraw events) function vim.api.nvim_input_mouse(button, action, modifier, grid, row, col) end ---- Gets the current list of buffer handles +--- Gets the current list of buffers. --- --- Includes unlisted (unloaded/deleted) buffers, like `:ls!`. --- Use `nvim_buf_is_loaded()` to check if a buffer is loaded. --- ---- @return integer[] # List of buffer handles +--- @return integer[] # List of buffer ids function vim.api.nvim_list_bufs() end --- Get information about all open channels. @@ -1622,7 +1624,7 @@ function vim.api.nvim_list_tabpages() end --- - "chan" |channel-id| of remote UI function vim.api.nvim_list_uis() end ---- Gets the current list of window handles. +--- Gets the current list of all `window-ID`s in all tabpages. --- --- @return integer[] # List of |window-ID|s function vim.api.nvim_list_wins() end @@ -2069,7 +2071,7 @@ function vim.api.nvim_select_popupmenu_item(item, insert, finish, opts) end --- Sets the current window's buffer to `buffer`. --- ---- @param buffer integer Buffer handle +--- @param buffer integer Buffer id function vim.api.nvim_set_current_buf(buffer) end --- Changes the global working directory. @@ -2361,7 +2363,7 @@ function vim.api.nvim_win_del_var(window, name) end --- Gets the current buffer in a window --- --- @param window integer `window-ID`, or 0 for current window ---- @return integer # Buffer handle +--- @return integer # Buffer id function vim.api.nvim_win_get_buf(window) end --- Gets window configuration. @@ -2446,7 +2448,7 @@ function vim.api.nvim_win_is_valid(window) end --- Sets the current buffer in a window, without side effects --- --- @param window integer `window-ID`, or 0 for current window ---- @param buffer integer Buffer handle +--- @param buffer integer Buffer id function vim.api.nvim_win_set_buf(window, buffer) end --- Configures window layout. Cannot be used to move the last window in a -- cgit From f96606371c13fd10280d737a4e3e2ae9149c2067 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 9 Mar 2025 23:56:22 +0100 Subject: docs: misc --- runtime/lua/vim/_meta/api.lua | 9 +++------ 1 file changed, 3 insertions(+), 6 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 69cb424254..ece3c1854b 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -485,10 +485,7 @@ function vim.api.nvim_buf_get_offset(buffer, index) end --- @return any function vim.api.nvim_buf_get_option(buffer, name) end ---- Gets a range from the buffer. ---- ---- This differs from `nvim_buf_get_lines()` in that it allows retrieving only ---- portions of a line. +--- Gets a range from the buffer (may be partial lines, unlike `nvim_buf_get_lines()`). --- --- Indexing is zero-based. Row indices are end-inclusive, and column indices --- are end-exclusive. @@ -698,7 +695,7 @@ function vim.api.nvim_buf_set_keymap(buffer, mode, lhs, rhs, opts) end --- --- Indexing is zero-based, end-exclusive. Negative indices are interpreted --- as length+1+index: -1 refers to the index past the end. So to change ---- or delete the last element use start=-2 and end=-1. +--- or delete the last line use start=-2 and end=-1. --- --- To insert lines at a given index, set `start` and `end` to the same index. --- To delete a range of lines, set `replacement` to an empty array. @@ -2089,7 +2086,7 @@ function vim.api.nvim_set_current_line(line) end --- @param tabpage integer `tab-ID` to focus function vim.api.nvim_set_current_tabpage(tabpage) end ---- Sets the current window. Also changes tabpage, if necessary. +--- Sets the current window (and tabpage, implicitly). --- --- @param window integer `window-ID` to focus function vim.api.nvim_set_current_win(window) end -- cgit