diff options
| -rw-r--r-- | runtime/doc/api.txt | 84 | ||||
| -rw-r--r-- | runtime/doc/lsp.txt | 4 | ||||
| -rw-r--r-- | runtime/doc/tabpage.txt | 11 | ||||
| -rw-r--r-- | runtime/doc/treesitter.txt | 2 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/api.lua | 84 | ||||
| -rw-r--r-- | runtime/lua/vim/lsp/util.lua | 6 | ||||
| -rw-r--r-- | runtime/lua/vim/treesitter.lua | 2 | ||||
| -rw-r--r-- | src/nvim/api/deprecated.c | 12 | ||||
| -rw-r--r-- | src/nvim/api/tabpage.c | 20 | ||||
| -rw-r--r-- | src/nvim/api/vim.c | 20 | ||||
| -rw-r--r-- | src/nvim/api/win_config.c | 6 | ||||
| -rw-r--r-- | src/nvim/api/window.c | 38 |
12 files changed, 150 insertions, 139 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 760d0804a6..b120c09468 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -810,13 +810,13 @@ nvim_get_current_tabpage() *nvim_get_current_tabpage()* Gets the current tabpage. Return: ~ - Tabpage handle + |tab-ID| nvim_get_current_win() *nvim_get_current_win()* Gets the current window. Return: ~ - Window handle + |window-ID| nvim_get_hl({ns_id}, {opts}) *nvim_get_hl()* Gets all or specific highlight groups in a namespace. @@ -1032,10 +1032,10 @@ nvim_list_runtime_paths() *nvim_list_runtime_paths()* List of paths nvim_list_tabpages() *nvim_list_tabpages()* - Gets the current list of tabpage handles. + Gets the current list of |tab-ID|s. Return: ~ - List of tabpage handles + List of |tab-ID|s nvim_list_uis() *nvim_list_uis()* Gets a list of dictionaries representing attached UIs. @@ -1058,7 +1058,7 @@ nvim_list_wins() *nvim_list_wins()* Gets the current list of window handles. Return: ~ - List of window handles + List of |window-ID|s nvim_load_context({dict}) *nvim_load_context()* Sets the current editor state from the given |context| map. @@ -1269,7 +1269,7 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) icon. .png or .svg format is preferred. nvim_set_current_buf({buffer}) *nvim_set_current_buf()* - Sets the current buffer. + Sets the current window's buffer to `buffer`. Attributes: ~ not allowed when |textlock| is active or in the |cmdwin| @@ -1284,7 +1284,7 @@ nvim_set_current_dir({dir}) *nvim_set_current_dir()* • {dir} Directory path nvim_set_current_line({line}) *nvim_set_current_line()* - Sets the current line. + Sets the text on the current line. Attributes: ~ not allowed when |textlock| is active @@ -1299,16 +1299,16 @@ nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()* not allowed when |textlock| is active or in the |cmdwin| Parameters: ~ - • {tabpage} Tabpage handle + • {tabpage} |tab-ID| to focus nvim_set_current_win({window}) *nvim_set_current_win()* - Sets the current window. + Sets the current window. Also changes tabpage, if necessary. Attributes: ~ not allowed when |textlock| is active or in the |cmdwin| Parameters: ~ - • {window} Window handle + • {window} |window-ID| to focus nvim_set_hl({ns_id}, {name}, {val}) *nvim_set_hl()* Sets a highlight group. @@ -2824,7 +2824,7 @@ nvim_win_call({window}, {fun}) *nvim_win_call()* Lua |vim.api| only Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window • {fun} Function to call inside the window (currently Lua callable only) @@ -2842,7 +2842,7 @@ nvim_win_close({window}, {force}) *nvim_win_close()* not allowed when |textlock| is active Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window • {force} Behave like `:close!` The last window of a buffer with unwritten changes can be closed. The buffer will become hidden, even if 'hidden' is not set. @@ -2851,14 +2851,14 @@ nvim_win_del_var({window}, {name}) *nvim_win_del_var()* Removes a window-scoped (w:) variable Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window • {name} Variable name nvim_win_get_buf({window}) *nvim_win_get_buf()* Gets the current buffer in a window Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window Return: ~ Buffer handle @@ -2869,7 +2869,7 @@ nvim_win_get_cursor({window}) *nvim_win_get_cursor()* positions). |api-indexing| Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window Return: ~ (row, col) tuple @@ -2881,7 +2881,7 @@ nvim_win_get_height({window}) *nvim_win_get_height()* Gets the window height Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window Return: ~ Height as a count of rows @@ -2890,7 +2890,7 @@ nvim_win_get_number({window}) *nvim_win_get_number()* Gets the window number Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window Return: ~ Window number @@ -2899,7 +2899,7 @@ nvim_win_get_position({window}) *nvim_win_get_position()* Gets the window position in display cells. First position is zero. Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window Return: ~ (row, col) tuple with the window position @@ -2908,7 +2908,7 @@ nvim_win_get_tabpage({window}) *nvim_win_get_tabpage()* Gets the window tabpage Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window Return: ~ Tabpage that contains the window @@ -2917,7 +2917,7 @@ nvim_win_get_var({window}, {name}) *nvim_win_get_var()* Gets a window-scoped (w:) variable Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window • {name} Variable name Return: ~ @@ -2927,7 +2927,7 @@ nvim_win_get_width({window}) *nvim_win_get_width()* Gets the window width Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window Return: ~ Width as a count of columns @@ -2944,13 +2944,13 @@ nvim_win_hide({window}) *nvim_win_hide()* not allowed when |textlock| is active Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window nvim_win_is_valid({window}) *nvim_win_is_valid()* Checks if a window is valid Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window Return: ~ true if the window is valid, false otherwise @@ -2962,7 +2962,7 @@ nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()* not allowed when |textlock| is active Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window • {buffer} Buffer handle nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()* @@ -2970,14 +2970,14 @@ nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()* scrolls the window even if it is not the current one. Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window • {pos} (row, col) tuple representing the new position nvim_win_set_height({window}, {height}) *nvim_win_set_height()* Sets the window height. Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window • {height} Height as a count of rows nvim_win_set_hl_ns({window}, {ns_id}) *nvim_win_set_hl_ns()* @@ -2994,7 +2994,7 @@ nvim_win_set_var({window}, {name}, {value}) *nvim_win_set_var()* Sets a window-scoped (w:) variable Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window • {name} Variable name • {value} Variable value @@ -3003,7 +3003,7 @@ nvim_win_set_width({window}, {width}) *nvim_win_set_width()* vertically. Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window • {width} Width as a count of columns nvim_win_text_height({window}, {opts}) *nvim_win_text_height()* @@ -3019,7 +3019,7 @@ nvim_win_text_height({window}, {opts}) *nvim_win_text_height()* Line indexing is similar to |nvim_buf_get_text()|. Parameters: ~ - • {window} Window handle, or 0 for current window. + • {window} |window-ID|, or 0 for current window. • {opts} Optional parameters: • start_row: Starting line index, 0-based inclusive. When omitted start at the very top. @@ -3224,7 +3224,7 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()* • split: Split direction: "left", "right", "above", "below". Return: ~ - Window handle, or 0 on error + |window-ID|, or 0 on error nvim_win_get_config({window}) *nvim_win_get_config()* Gets window configuration. @@ -3234,7 +3234,7 @@ nvim_win_get_config({window}) *nvim_win_get_config()* `relative` is empty for normal windows. Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window Return: ~ Map defining the window configuration, see |nvim_open_win()| @@ -3247,7 +3247,7 @@ nvim_win_set_config({window}, {config}) *nvim_win_set_config()* `row`/`col` and `relative` must be reconfigured together. Parameters: ~ - • {window} Window handle, or 0 for current window + • {window} |window-ID|, or 0 for current window • {config} Map defining the window configuration, see |nvim_open_win()| See also: ~ @@ -3261,14 +3261,14 @@ nvim_tabpage_del_var({tabpage}, {name}) *nvim_tabpage_del_var()* Removes a tab-scoped (t:) variable Parameters: ~ - • {tabpage} Tabpage handle, or 0 for current tabpage + • {tabpage} |tab-ID|, or 0 for current tabpage • {name} Variable name nvim_tabpage_get_number({tabpage}) *nvim_tabpage_get_number()* Gets the tabpage number Parameters: ~ - • {tabpage} Tabpage handle, or 0 for current tabpage + • {tabpage} |tab-ID|, or 0 for current tabpage Return: ~ Tabpage number @@ -3277,7 +3277,7 @@ nvim_tabpage_get_var({tabpage}, {name}) *nvim_tabpage_get_var()* Gets a tab-scoped (t:) variable Parameters: ~ - • {tabpage} Tabpage handle, or 0 for current tabpage + • {tabpage} |tab-ID|, or 0 for current tabpage • {name} Variable name Return: ~ @@ -3287,16 +3287,16 @@ nvim_tabpage_get_win({tabpage}) *nvim_tabpage_get_win()* Gets the current window in a tabpage Parameters: ~ - • {tabpage} Tabpage handle, or 0 for current tabpage + • {tabpage} |tab-ID|, or 0 for current tabpage Return: ~ - Window handle + |window-ID| nvim_tabpage_is_valid({tabpage}) *nvim_tabpage_is_valid()* Checks if a tabpage is valid Parameters: ~ - • {tabpage} Tabpage handle, or 0 for current tabpage + • {tabpage} |tab-ID|, or 0 for current tabpage Return: ~ true if the tabpage is valid, false otherwise @@ -3305,7 +3305,7 @@ nvim_tabpage_list_wins({tabpage}) *nvim_tabpage_list_wins()* Gets the windows in a tabpage Parameters: ~ - • {tabpage} Tabpage handle, or 0 for current tabpage + • {tabpage} |tab-ID|, or 0 for current tabpage Return: ~ List of windows in `tabpage` @@ -3315,7 +3315,7 @@ nvim_tabpage_set_var({tabpage}, {name}, {value}) Sets a tab-scoped (t:) variable Parameters: ~ - • {tabpage} Tabpage handle, or 0 for current tabpage + • {tabpage} |tab-ID|, or 0 for current tabpage • {name} Variable name • {value} Variable value @@ -3323,8 +3323,8 @@ nvim_tabpage_set_win({tabpage}, {win}) *nvim_tabpage_set_win()* Sets the current window in a tabpage Parameters: ~ - • {tabpage} Tabpage handle, or 0 for current tabpage - • {win} Window handle, must already belong to {tabpage} + • {tabpage} |tab-ID|, or 0 for current tabpage + • {win} |window-ID|, must already belong to {tabpage} ============================================================================== diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index 37f4d43e2c..9216255185 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -2234,7 +2234,7 @@ make_position_params({window}, {position_encoding}) cursor position. Parameters: ~ - • {window} (`integer?`) window handle or 0 for current, + • {window} (`integer?`) |window-ID| or 0 for current, defaults to current • {position_encoding} (`'utf-8'|'utf-16'|'utf-32'`) @@ -2252,7 +2252,7 @@ make_range_params({window}, {position_encoding}) `textDocument/rangeFormatting`. Parameters: ~ - • {window} (`integer?`) window handle or 0 for current, + • {window} (`integer?`) |window-ID| or 0 for current, defaults to current • {position_encoding} (`"utf-8"|"utf-16"|"utf-32"`) diff --git a/runtime/doc/tabpage.txt b/runtime/doc/tabpage.txt index 7bfa36e8ab..deb5bfb9ad 100644 --- a/runtime/doc/tabpage.txt +++ b/runtime/doc/tabpage.txt @@ -32,6 +32,17 @@ Tabs are also a nice way to edit a buffer temporarily without changing the current window layout. Open a new tab page, do whatever you want to do and close the tab page. + *tab-ID* *tabid* *tabpageid* +Each tab page has a unique identifier called the tab ID. This identifier will +not change within a Vim session -- even when rearranging tabs. +|nvim_get_current_tabpage()| returns the tab ID and |nvim_list_tabpages()| +lists tab IDs in the order they're displayed. Additionally, the tabs are +numbered from left to right starting at 1: this is the tab number returned by +|tabpagenr()|. However, the tab number may change when tabs are opened, +closed, or rearranged. |nvim_tabpage_get_number()| converts a tab ID to a tab +number. + + ============================================================================== 2. Commands *tab-page-commands* diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt index db23576192..8c63f0b5db 100644 --- a/runtime/doc/treesitter.txt +++ b/runtime/doc/treesitter.txt @@ -914,7 +914,7 @@ get_captures_at_cursor({winnr}) Returns a list of highlight capture names under the cursor Parameters: ~ - • {winnr} (`integer?`) Window handle or 0 for current window (default) + • {winnr} (`integer?`) |window-ID| or 0 for current window (default) Return: ~ (`string[]`) List of capture names diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 94469a768c..af194aa70e 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1361,12 +1361,12 @@ function vim.api.nvim_get_current_line() end --- Gets the current tabpage. --- ---- @return integer # Tabpage handle +--- @return integer # |tab-ID| function vim.api.nvim_get_current_tabpage() end --- Gets the current window. --- ---- @return integer # Window handle +--- @return integer # |window-ID| function vim.api.nvim_get_current_win() end --- Gets all or specific highlight groups in a namespace. @@ -1619,9 +1619,9 @@ function vim.api.nvim_list_chans() end --- @return string[] # List of paths function vim.api.nvim_list_runtime_paths() end ---- Gets the current list of tabpage handles. +--- Gets the current list of `tab-ID`s. --- ---- @return integer[] # List of tabpage handles +--- @return integer[] # List of |tab-ID|s function vim.api.nvim_list_tabpages() end --- Gets a list of dictionaries representing attached UIs. @@ -1644,7 +1644,7 @@ function vim.api.nvim_list_uis() end --- Gets the current list of window handles. --- ---- @return integer[] # List of window handles +--- @return integer[] # List of |window-ID|s function vim.api.nvim_list_wins() end --- Sets the current editor state from the given `context` map. @@ -1870,7 +1870,7 @@ function vim.api.nvim_open_term(buffer, opts) end --- - hide: If true the floating window will be hidden. --- - vertical: Split vertically `:vertical`. --- - split: Split direction: "left", "right", "above", "below". ---- @return integer # Window handle, or 0 on error +--- @return integer # |window-ID|, or 0 on error function vim.api.nvim_open_win(buffer, enter, config) end --- @deprecated @@ -2087,7 +2087,7 @@ function vim.api.nvim_replace_termcodes(str, from_part, do_lt, special) end --- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use. function vim.api.nvim_select_popupmenu_item(item, insert, finish, opts) end ---- Sets the current buffer. +--- Sets the current window's buffer to `buffer`. --- --- @param buffer integer Buffer handle function vim.api.nvim_set_current_buf(buffer) end @@ -2097,19 +2097,19 @@ function vim.api.nvim_set_current_buf(buffer) end --- @param dir string Directory path function vim.api.nvim_set_current_dir(dir) end ---- Sets the current line. +--- Sets the text on the current line. --- --- @param line string Line contents function vim.api.nvim_set_current_line(line) end --- Sets the current tabpage. --- ---- @param tabpage integer Tabpage handle +--- @param tabpage integer `tab-ID` to focus function vim.api.nvim_set_current_tabpage(tabpage) end ---- Sets the current window. +--- Sets the current window. Also changes tabpage, if necessary. --- ---- @param window integer Window handle +--- @param window integer `window-ID` to focus function vim.api.nvim_set_current_win(window) end --- Set or change decoration provider for a `namespace` @@ -2305,52 +2305,52 @@ function vim.api.nvim_strwidth(text) end --- Removes a tab-scoped (t:) variable --- ---- @param tabpage integer Tabpage handle, or 0 for current tabpage +--- @param tabpage integer `tab-ID`, or 0 for current tabpage --- @param name string Variable name function vim.api.nvim_tabpage_del_var(tabpage, name) end --- Gets the tabpage number --- ---- @param tabpage integer Tabpage handle, or 0 for current tabpage +--- @param tabpage integer `tab-ID`, or 0 for current tabpage --- @return integer # Tabpage number function vim.api.nvim_tabpage_get_number(tabpage) end --- Gets a tab-scoped (t:) variable --- ---- @param tabpage integer Tabpage handle, or 0 for current tabpage +--- @param tabpage integer `tab-ID`, or 0 for current tabpage --- @param name string Variable name --- @return any # Variable value function vim.api.nvim_tabpage_get_var(tabpage, name) end --- Gets the current window in a tabpage --- ---- @param tabpage integer Tabpage handle, or 0 for current tabpage ---- @return integer # Window handle +--- @param tabpage integer `tab-ID`, or 0 for current tabpage +--- @return integer # |window-ID| function vim.api.nvim_tabpage_get_win(tabpage) end --- Checks if a tabpage is valid --- ---- @param tabpage integer Tabpage handle, or 0 for current tabpage +--- @param tabpage integer `tab-ID`, or 0 for current tabpage --- @return boolean # true if the tabpage is valid, false otherwise function vim.api.nvim_tabpage_is_valid(tabpage) end --- Gets the windows in a tabpage --- ---- @param tabpage integer Tabpage handle, or 0 for current tabpage +--- @param tabpage integer `tab-ID`, or 0 for current tabpage --- @return integer[] # List of windows in `tabpage` function vim.api.nvim_tabpage_list_wins(tabpage) end --- Sets a tab-scoped (t:) variable --- ---- @param tabpage integer Tabpage handle, or 0 for current tabpage +--- @param tabpage integer `tab-ID`, or 0 for current tabpage --- @param name string Variable name --- @param value any Variable value function vim.api.nvim_tabpage_set_var(tabpage, name, value) end --- Sets the current window in a tabpage --- ---- @param tabpage integer Tabpage handle, or 0 for current tabpage ---- @param win integer Window handle, must already belong to {tabpage} +--- @param tabpage integer `tab-ID`, or 0 for current tabpage +--- @param win integer `window-ID`, must already belong to {tabpage} function vim.api.nvim_tabpage_set_win(tabpage, win) end --- Calls a function with window as temporary current window. @@ -2358,7 +2358,7 @@ function vim.api.nvim_tabpage_set_win(tabpage, win) end --- --- @see `:help win_execute()` --- @see vim.api.nvim_buf_call ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window --- @param fun function Function to call inside the window (currently Lua callable --- only) --- @return any # Return value of function. @@ -2366,7 +2366,7 @@ function vim.api.nvim_win_call(window, fun) end --- Closes the window (like `:close` with a `window-ID`). --- ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window --- @param force boolean Behave like `:close!` The last window of a buffer with --- unwritten changes can be closed. The buffer will become --- hidden, even if 'hidden' is not set. @@ -2374,13 +2374,13 @@ function vim.api.nvim_win_close(window, force) end --- Removes a window-scoped (w:) variable --- ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window --- @param name string Variable name function vim.api.nvim_win_del_var(window, name) end --- Gets the current buffer in a window --- ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window --- @return integer # Buffer handle function vim.api.nvim_win_get_buf(window) end @@ -2390,7 +2390,7 @@ function vim.api.nvim_win_get_buf(window) end --- --- `relative` is empty for normal windows. --- ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window --- @return vim.api.keyset.win_config # Map defining the window configuration, see |nvim_open_win()| function vim.api.nvim_win_get_config(window) end @@ -2400,19 +2400,19 @@ function vim.api.nvim_win_get_config(window) end --- --- --- @see `:help getcurpos()` ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window --- @return integer[] # (row, col) tuple function vim.api.nvim_win_get_cursor(window) end --- Gets the window height --- ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window --- @return integer # Height as a count of rows function vim.api.nvim_win_get_height(window) end --- Gets the window number --- ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window --- @return integer # Window number function vim.api.nvim_win_get_number(window) end @@ -2424,26 +2424,26 @@ function vim.api.nvim_win_get_option(window, name) end --- Gets the window position in display cells. First position is zero. --- ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window --- @return integer[] # (row, col) tuple with the window position function vim.api.nvim_win_get_position(window) end --- Gets the window tabpage --- ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window --- @return integer # Tabpage that contains the window function vim.api.nvim_win_get_tabpage(window) end --- Gets a window-scoped (w:) variable --- ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window --- @param name string Variable name --- @return any # Variable value function vim.api.nvim_win_get_var(window, name) end --- Gets the window width --- ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window --- @return integer # Width as a count of columns function vim.api.nvim_win_get_width(window) end @@ -2454,18 +2454,18 @@ function vim.api.nvim_win_get_width(window) end --- or 'bufhidden' is `unload`, `delete` or `wipe` as opposed to `:close` or --- `nvim_win_close()`, which will close the buffer. --- ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window function vim.api.nvim_win_hide(window) end --- Checks if a window is valid --- ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window --- @return boolean # true if the window is valid, false otherwise function vim.api.nvim_win_is_valid(window) end --- Sets the current buffer in a window, without side effects --- ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window --- @param buffer integer Buffer handle function vim.api.nvim_win_set_buf(window, buffer) end @@ -2477,7 +2477,7 @@ function vim.api.nvim_win_set_buf(window, buffer) end --- --- --- @see vim.api.nvim_open_win ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, 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 @@ -2485,13 +2485,13 @@ function vim.api.nvim_win_set_config(window, config) end --- Sets the (1,0)-indexed cursor position in the window. `api-indexing` --- This scrolls the window even if it is not the current one. --- ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window --- @param pos integer[] (row, col) tuple representing the new position function vim.api.nvim_win_set_cursor(window, pos) end --- Sets the window height. --- ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window --- @param height integer Height as a count of rows function vim.api.nvim_win_set_height(window, height) end @@ -2513,7 +2513,7 @@ function vim.api.nvim_win_set_option(window, name, value) end --- Sets a window-scoped (w:) variable --- ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window --- @param name string Variable name --- @param value any Variable value function vim.api.nvim_win_set_var(window, name, value) end @@ -2521,7 +2521,7 @@ function vim.api.nvim_win_set_var(window, name, value) end --- Sets the window width. This will only succeed if the screen is split --- vertically. --- ---- @param window integer Window handle, or 0 for current window +--- @param window integer `window-ID`, or 0 for current window --- @param width integer Width as a count of columns function vim.api.nvim_win_set_width(window, width) end @@ -2537,7 +2537,7 @@ function vim.api.nvim_win_set_width(window, width) end --- Line indexing is similar to `nvim_buf_get_text()`. --- --- @see `:help virtcol()` for text width. ---- @param window integer Window handle, or 0 for current window. +--- @param window integer `window-ID`, or 0 for current window. --- @param opts vim.api.keyset.win_text_height Optional parameters: --- - start_row: Starting line index, 0-based inclusive. --- When omitted start at the very top. diff --git a/runtime/lua/vim/lsp/util.lua b/runtime/lua/vim/lsp/util.lua index cacf7824c4..b0567e3b59 100644 --- a/runtime/lua/vim/lsp/util.lua +++ b/runtime/lua/vim/lsp/util.lua @@ -1896,7 +1896,7 @@ function M.try_trim_markdown_code_blocks(lines) return 'markdown' end ----@param window integer?: window handle or 0 for current, defaults to current +---@param window integer?: |window-ID| or 0 for current, defaults to current ---@param position_encoding 'utf-8'|'utf-16'|'utf-32' local function make_position_param(window, position_encoding) window = window or 0 @@ -1915,7 +1915,7 @@ end --- Creates a `TextDocumentPositionParams` object for the current buffer and cursor position. --- ----@param window integer?: window handle or 0 for current, defaults to current +---@param window integer?: |window-ID| or 0 for current, defaults to current ---@param position_encoding 'utf-8'|'utf-16'|'utf-32' ---@return lsp.TextDocumentPositionParams ---@see https://microsoft.github.io/language-server-protocol/specifications/specification-current/#textDocumentPositionParams @@ -1974,7 +1974,7 @@ end --- `textDocument/codeAction`, `textDocument/colorPresentation`, --- `textDocument/rangeFormatting`. --- ----@param window integer? window handle or 0 for current, defaults to current +---@param window integer?: |window-ID| or 0 for current, defaults to current ---@param position_encoding "utf-8"|"utf-16"|"utf-32" ---@return { textDocument: { uri: lsp.DocumentUri }, range: lsp.Range } function M.make_range_params(window, position_encoding) diff --git a/runtime/lua/vim/treesitter.lua b/runtime/lua/vim/treesitter.lua index 44372415fd..a5362202fb 100644 --- a/runtime/lua/vim/treesitter.lua +++ b/runtime/lua/vim/treesitter.lua @@ -306,7 +306,7 @@ end --- Returns a list of highlight capture names under the cursor --- ----@param winnr (integer|nil) Window handle or 0 for current window (default) +---@param winnr (integer|nil): |window-ID| or 0 for current window (default) --- ---@return string[] List of capture names function M.get_captures_at_cursor(winnr) diff --git a/src/nvim/api/deprecated.c b/src/nvim/api/deprecated.c index 2f29ed38ef..767a7a8bc8 100644 --- a/src/nvim/api/deprecated.c +++ b/src/nvim/api/deprecated.c @@ -488,7 +488,7 @@ Object buffer_del_var(Buffer buffer, String name, Arena *arena, Error *err) /// /// @deprecated /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param name Variable name /// @param value Variable value /// @param[out] err Error details, if any @@ -512,7 +512,7 @@ Object window_set_var(Window window, String name, Object value, Arena *arena, Er /// /// @deprecated /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param name variable name /// @param[out] err Error details, if any /// @return Old value @@ -532,7 +532,7 @@ Object window_del_var(Window window, String name, Arena *arena, Error *err) /// /// @deprecated /// -/// @param tabpage Tabpage handle, or 0 for current tabpage +/// @param tabpage |tab-ID|, or 0 for current tabpage /// @param name Variable name /// @param value Variable value /// @param[out] err Error details, if any @@ -556,7 +556,7 @@ Object tabpage_set_var(Tabpage tabpage, String name, Object value, Arena *arena, /// /// @deprecated /// -/// @param tabpage Tabpage handle, or 0 for current tabpage +/// @param tabpage |tab-ID|, or 0 for current tabpage /// @param name Variable name /// @param[out] err Error details, if any /// @return Old value @@ -684,7 +684,7 @@ void nvim_buf_set_option(uint64_t channel_id, Buffer buffer, String name, Object /// Gets a window option value /// /// @deprecated -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param name Option name /// @param[out] err Error details, if any /// @return Option value @@ -707,7 +707,7 @@ Object nvim_win_get_option(Window window, String name, Error *err) /// /// @deprecated /// @param channel_id -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param name Option name /// @param value Option value /// @param[out] err Error details, if any diff --git a/src/nvim/api/tabpage.c b/src/nvim/api/tabpage.c index dce47cd99f..6673b2e6c2 100644 --- a/src/nvim/api/tabpage.c +++ b/src/nvim/api/tabpage.c @@ -17,7 +17,7 @@ /// Gets the windows in a tabpage /// -/// @param tabpage Tabpage handle, or 0 for current tabpage +/// @param tabpage |tab-ID|, or 0 for current tabpage /// @param[out] err Error details, if any /// @return List of windows in `tabpage` ArrayOf(Window) nvim_tabpage_list_wins(Tabpage tabpage, Arena *arena, Error *err) @@ -46,7 +46,7 @@ ArrayOf(Window) nvim_tabpage_list_wins(Tabpage tabpage, Arena *arena, Error *err /// Gets a tab-scoped (t:) variable /// -/// @param tabpage Tabpage handle, or 0 for current tabpage +/// @param tabpage |tab-ID|, or 0 for current tabpage /// @param name Variable name /// @param[out] err Error details, if any /// @return Variable value @@ -64,7 +64,7 @@ Object nvim_tabpage_get_var(Tabpage tabpage, String name, Arena *arena, Error *e /// Sets a tab-scoped (t:) variable /// -/// @param tabpage Tabpage handle, or 0 for current tabpage +/// @param tabpage |tab-ID|, or 0 for current tabpage /// @param name Variable name /// @param value Variable value /// @param[out] err Error details, if any @@ -82,7 +82,7 @@ void nvim_tabpage_set_var(Tabpage tabpage, String name, Object value, Error *err /// Removes a tab-scoped (t:) variable /// -/// @param tabpage Tabpage handle, or 0 for current tabpage +/// @param tabpage |tab-ID|, or 0 for current tabpage /// @param name Variable name /// @param[out] err Error details, if any void nvim_tabpage_del_var(Tabpage tabpage, String name, Error *err) @@ -99,9 +99,9 @@ void nvim_tabpage_del_var(Tabpage tabpage, String name, Error *err) /// Gets the current window in a tabpage /// -/// @param tabpage Tabpage handle, or 0 for current tabpage +/// @param tabpage |tab-ID|, or 0 for current tabpage /// @param[out] err Error details, if any -/// @return Window handle +/// @return |window-ID| Window nvim_tabpage_get_win(Tabpage tabpage, Error *err) FUNC_API_SINCE(1) { @@ -125,8 +125,8 @@ Window nvim_tabpage_get_win(Tabpage tabpage, Error *err) /// Sets the current window in a tabpage /// -/// @param tabpage Tabpage handle, or 0 for current tabpage -/// @param win Window handle, must already belong to {tabpage} +/// @param tabpage |tab-ID|, or 0 for current tabpage +/// @param win |window-ID|, must already belong to {tabpage} /// @param[out] err Error details, if any void nvim_tabpage_set_win(Tabpage tabpage, Window win, Error *err) FUNC_API_SINCE(12) @@ -158,7 +158,7 @@ void nvim_tabpage_set_win(Tabpage tabpage, Window win, Error *err) /// Gets the tabpage number /// -/// @param tabpage Tabpage handle, or 0 for current tabpage +/// @param tabpage |tab-ID|, or 0 for current tabpage /// @param[out] err Error details, if any /// @return Tabpage number Integer nvim_tabpage_get_number(Tabpage tabpage, Error *err) @@ -175,7 +175,7 @@ Integer nvim_tabpage_get_number(Tabpage tabpage, Error *err) /// Checks if a tabpage is valid /// -/// @param tabpage Tabpage handle, or 0 for current tabpage +/// @param tabpage |tab-ID|, or 0 for current tabpage /// @return true if the tabpage is valid, false otherwise Boolean nvim_tabpage_is_valid(Tabpage tabpage) FUNC_API_SINCE(1) diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 02aa73d98d..3a89e44938 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -661,7 +661,7 @@ String nvim_get_current_line(Arena *arena, Error *err) return buffer_get_line(curbuf->handle, curwin->w_cursor.lnum - 1, arena, err); } -/// Sets the current line. +/// Sets the text on the current line. /// /// @param line Line contents /// @param[out] err Error details, if any @@ -823,7 +823,7 @@ Buffer nvim_get_current_buf(void) return curbuf->handle; } -/// Sets the current buffer. +/// Sets the current window's buffer to `buffer`. /// /// @param buffer Buffer handle /// @param[out] err Error details, if any @@ -844,7 +844,7 @@ void nvim_set_current_buf(Buffer buffer, Error *err) /// Gets the current list of window handles. /// -/// @return List of window handles +/// @return List of |window-ID|s ArrayOf(Window) nvim_list_wins(Arena *arena) FUNC_API_SINCE(1) { @@ -865,16 +865,16 @@ ArrayOf(Window) nvim_list_wins(Arena *arena) /// Gets the current window. /// -/// @return Window handle +/// @return |window-ID| Window nvim_get_current_win(void) FUNC_API_SINCE(1) { return curwin->handle; } -/// Sets the current window. +/// Sets the current window. Also changes tabpage, if necessary. /// -/// @param window Window handle +/// @param window |window-ID| to focus /// @param[out] err Error details, if any void nvim_set_current_win(Window window, Error *err) FUNC_API_SINCE(1) @@ -1106,9 +1106,9 @@ void nvim_chan_send(Integer chan, String data, Error *err) VALIDATE(!error, "%s", error, {}); } -/// Gets the current list of tabpage handles. +/// Gets the current list of |tab-ID|s. /// -/// @return List of tabpage handles +/// @return List of |tab-ID|s ArrayOf(Tabpage) nvim_list_tabpages(Arena *arena) FUNC_API_SINCE(1) { @@ -1129,7 +1129,7 @@ ArrayOf(Tabpage) nvim_list_tabpages(Arena *arena) /// Gets the current tabpage. /// -/// @return Tabpage handle +/// @return |tab-ID| Tabpage nvim_get_current_tabpage(void) FUNC_API_SINCE(1) { @@ -1138,7 +1138,7 @@ Tabpage nvim_get_current_tabpage(void) /// Sets the current tabpage. /// -/// @param tabpage Tabpage handle +/// @param tabpage |tab-ID| to focus /// @param[out] err Error details, if any void nvim_set_current_tabpage(Tabpage tabpage, Error *err) FUNC_API_SINCE(1) diff --git a/src/nvim/api/win_config.c b/src/nvim/api/win_config.c index 527689b17c..12bbd79dbd 100644 --- a/src/nvim/api/win_config.c +++ b/src/nvim/api/win_config.c @@ -214,7 +214,7 @@ /// /// @param[out] err Error details, if any /// -/// @return Window handle, or 0 on error +/// @return |window-ID|, or 0 on error Window nvim_open_win(Buffer buffer, Boolean enter, Dict(win_config) *config, Error *err) FUNC_API_SINCE(6) FUNC_API_TEXTLOCK_ALLOW_CMDWIN { @@ -387,7 +387,7 @@ static int win_split_flags(WinSplit split, bool toplevel) /// /// @see |nvim_open_win()| /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param config Map defining the window configuration, /// see |nvim_open_win()| /// @param[out] err Error details, if any @@ -694,7 +694,7 @@ static void config_put_bordertext(Dict(win_config) *config, WinConfig *fconfig, /// /// `relative` is empty for normal windows. /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param[out] err Error details, if any /// @return Map defining the window configuration, see |nvim_open_win()| Dict(win_config) nvim_win_get_config(Window window, Arena *arena, Error *err) diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c index d968af421d..c902a6effb 100644 --- a/src/nvim/api/window.c +++ b/src/nvim/api/window.c @@ -32,7 +32,7 @@ /// Gets the current buffer in a window /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param[out] err Error details, if any /// @return Buffer handle Buffer nvim_win_get_buf(Window window, Error *err) @@ -49,7 +49,7 @@ Buffer nvim_win_get_buf(Window window, Error *err) /// Sets the current buffer in a window, without side effects /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param buffer Buffer handle /// @param[out] err Error details, if any void nvim_win_set_buf(Window window, Buffer buffer, Error *err) @@ -75,7 +75,7 @@ void nvim_win_set_buf(Window window, Buffer buffer, Error *err) /// /// @see |getcurpos()| /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param[out] err Error details, if any /// @return (row, col) tuple ArrayOf(Integer, 2) nvim_win_get_cursor(Window window, Arena *arena, Error *err) @@ -96,7 +96,7 @@ ArrayOf(Integer, 2) nvim_win_get_cursor(Window window, Arena *arena, Error *err) /// Sets the (1,0)-indexed cursor position in the window. |api-indexing| /// This scrolls the window even if it is not the current one. /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param pos (row, col) tuple representing the new position /// @param[out] err Error details, if any void nvim_win_set_cursor(Window window, ArrayOf(Integer, 2) pos, Error *err) @@ -152,7 +152,7 @@ void nvim_win_set_cursor(Window window, ArrayOf(Integer, 2) pos, Error *err) /// Gets the window height /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param[out] err Error details, if any /// @return Height as a count of rows Integer nvim_win_get_height(Window window, Error *err) @@ -169,7 +169,7 @@ Integer nvim_win_get_height(Window window, Error *err) /// Sets the window height. /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param height Height as a count of rows /// @param[out] err Error details, if any void nvim_win_set_height(Window window, Integer height, Error *err) @@ -188,7 +188,7 @@ void nvim_win_set_height(Window window, Integer height, Error *err) /// Gets the window width /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param[out] err Error details, if any /// @return Width as a count of columns Integer nvim_win_get_width(Window window, Error *err) @@ -206,7 +206,7 @@ Integer nvim_win_get_width(Window window, Error *err) /// Sets the window width. This will only succeed if the screen is split /// vertically. /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param width Width as a count of columns /// @param[out] err Error details, if any void nvim_win_set_width(Window window, Integer width, Error *err) @@ -225,7 +225,7 @@ void nvim_win_set_width(Window window, Integer width, Error *err) /// Gets a window-scoped (w:) variable /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param name Variable name /// @param[out] err Error details, if any /// @return Variable value @@ -243,7 +243,7 @@ Object nvim_win_get_var(Window window, String name, Arena *arena, Error *err) /// Sets a window-scoped (w:) variable /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param name Variable name /// @param value Variable value /// @param[out] err Error details, if any @@ -261,7 +261,7 @@ void nvim_win_set_var(Window window, String name, Object value, Error *err) /// Removes a window-scoped (w:) variable /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param name Variable name /// @param[out] err Error details, if any void nvim_win_del_var(Window window, String name, Error *err) @@ -278,7 +278,7 @@ void nvim_win_del_var(Window window, String name, Error *err) /// Gets the window position in display cells. First position is zero. /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param[out] err Error details, if any /// @return (row, col) tuple with the window position ArrayOf(Integer, 2) nvim_win_get_position(Window window, Arena *arena, Error *err) @@ -298,7 +298,7 @@ ArrayOf(Integer, 2) nvim_win_get_position(Window window, Arena *arena, Error *er /// Gets the window tabpage /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param[out] err Error details, if any /// @return Tabpage that contains the window Tabpage nvim_win_get_tabpage(Window window, Error *err) @@ -316,7 +316,7 @@ Tabpage nvim_win_get_tabpage(Window window, Error *err) /// Gets the window number /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param[out] err Error details, if any /// @return Window number Integer nvim_win_get_number(Window window, Error *err) @@ -337,7 +337,7 @@ Integer nvim_win_get_number(Window window, Error *err) /// Checks if a window is valid /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @return true if the window is valid, false otherwise Boolean nvim_win_is_valid(Window window) FUNC_API_SINCE(1) @@ -355,7 +355,7 @@ Boolean nvim_win_is_valid(Window window) /// or 'bufhidden' is `unload`, `delete` or `wipe` as opposed to |:close| or /// |nvim_win_close()|, which will close the buffer. /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param[out] err Error details, if any void nvim_win_hide(Window window, Error *err) FUNC_API_SINCE(7) @@ -381,7 +381,7 @@ void nvim_win_hide(Window window, Error *err) /// Closes the window (like |:close| with a |window-ID|). /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param force Behave like `:close!` The last window of a buffer with /// unwritten changes can be closed. The buffer will become /// hidden, even if 'hidden' is not set. @@ -406,7 +406,7 @@ void nvim_win_close(Window window, Boolean force, Error *err) /// @see |win_execute()| /// @see |nvim_buf_call()| /// -/// @param window Window handle, or 0 for current window +/// @param window |window-ID|, or 0 for current window /// @param fun Function to call inside the window (currently Lua callable /// only) /// @param[out] err Error details, if any @@ -472,7 +472,7 @@ void nvim_win_set_hl_ns(Window window, Integer ns_id, Error *err) /// /// Line indexing is similar to |nvim_buf_get_text()|. /// -/// @param window Window handle, or 0 for current window. +/// @param window |window-ID|, or 0 for current window. /// @param opts Optional parameters: /// - start_row: Starting line index, 0-based inclusive. /// When omitted start at the very top. |