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

5 files changed, 48 insertions, 48 deletions

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.