doc: clarify window-id, tab-id, nvim_set_current_x #32528

Problem:
Descriptions are somewhat vague. nvim_set_current_line modifies contents
but nvim_set_current_buf does not, etc.

Solution:
- Make it clear that these functions accept or return a winid/tabid by
  linking to that concept in help.
- Only these few files use the term "handles", so replace them with the
  more conventional terminology.
- Add a new help section for tab-ID. This concept is unique to neovim
  because vim exposes tabnr, but not tab handles. This section is
  modelled after `:h winid`.

3 files changed, 46 insertions, 46 deletions

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)