mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-09-19 01:38:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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`.
This commit is contained in:
David Briscoe
2025-02-27 02:05:00 -08:00
committed by GitHub
parent 746139fa1e
commit 6a9555c0fa
12 changed files with 150 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
src/nvim/api/window.c
View File

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