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

7 files changed, 102 insertions, 91 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)