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

1 files changed, 19 insertions, 19 deletions

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.