docs(api): rename "handle" => "id"

src/nvim/api/buffer.c

@@ -67,7 +67,7 @@
 
 /// Returns the number of lines in the given buffer.
 ///
-/// @param buffer   Buffer handle, or 0 for current buffer
+/// @param buffer   Buffer id, or 0 for current buffer
 /// @param[out] err Error details, if any
 /// @return Line count, or 0 for unloaded buffer. |api-buffer|
 Integer nvim_buf_line_count(Buffer buffer, Error *err)
@@ -105,7 +105,7 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
 /// @see |api-buffer-updates-lua|
 ///
 /// @param channel_id
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
 /// @param send_buffer True if the initial notification should contain the
 ///        whole buffer: first notification will be `nvim_buf_lines_event`.
 ///        Else the first notification will be `nvim_buf_changedtick_event`.
@@ -114,7 +114,7 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
 ///             - on_lines: Lua callback invoked on change.
 ///               Return a truthy value (not `false` or `nil`) to detach. Args:
 ///               - the string "lines"
-///               - buffer handle
+///               - buffer id
 ///               - b:changedtick
 ///               - first line that changed (zero-indexed)
 ///               - last line that was changed
@@ -127,7 +127,7 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
 ///               change compared to on_lines.
 ///               Return a truthy value (not `false` or `nil`) to detach. Args:
 ///               - the string "bytes"
-///               - buffer handle
+///               - buffer id
 ///               - b:changedtick
 ///               - start row of the changed text (zero-indexed)
 ///               - start column of the changed text
@@ -144,15 +144,15 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
 ///             - on_changedtick: Lua callback invoked on changedtick
 ///               increment without text change. Args:
 ///               - the string "changedtick"
-///               - buffer handle
+///               - buffer id
 ///               - b:changedtick
 ///             - on_detach: Lua callback invoked on detach. Args:
 ///               - the string "detach"
-///               - buffer handle
+///               - buffer id
 ///             - on_reload: Lua callback invoked on reload. The entire buffer
 ///                          content should be considered changed. Args:
 ///               - the string "reload"
-///               - buffer handle
+///               - buffer id
 ///             - utf_sizes: include UTF-32 and UTF-16 size of the replaced
 ///               region, as args to `on_lines`.
 ///             - preview: also attach to command preview (i.e. 'inccommand')
@@ -212,7 +212,7 @@ Boolean nvim_buf_attach(uint64_t channel_id, Buffer buffer, Boolean send_buffer,
 /// @see |api-lua-detach| for detaching Lua callbacks
 ///
 /// @param channel_id
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
 /// @param[out] err Error details, if any
 /// @return False if detach failed (because the buffer isn't loaded);
 ///         otherwise True.
@@ -239,7 +239,7 @@ Boolean nvim_buf_detach(uint64_t channel_id, Buffer buffer, Error *err)
 /// `strict_indexing` is set.
 ///
 /// @param channel_id
-/// @param buffer           Buffer handle, or 0 for current buffer
+/// @param buffer           Buffer id, or 0 for current buffer
 /// @param start            First line index
 /// @param end              Last line index, exclusive
 /// @param strict_indexing  Whether out-of-bounds should be an error.
@@ -305,7 +305,7 @@ ArrayOf(String) nvim_buf_get_lines(uint64_t channel_id,
 /// @see |nvim_buf_set_text()|
 ///
 /// @param channel_id
-/// @param buffer           Buffer handle, or 0 for current buffer
+/// @param buffer           Buffer id, or 0 for current buffer
 /// @param start            First line index
 /// @param end              Last line index, exclusive
 /// @param strict_indexing  Whether out-of-bounds should be an error.
@@ -463,7 +463,7 @@ void nvim_buf_set_lines(uint64_t channel_id, Buffer buffer, Integer start, Integ
 /// @note Prefer |nvim_paste()| or |nvim_put()| to insert (instead of replace) text at cursor.
 ///
 /// @param channel_id
-/// @param buffer           Buffer handle, or 0 for current buffer
+/// @param buffer           Buffer id, or 0 for current buffer
 /// @param start_row        First line index
 /// @param start_col        Starting column (byte offset) on first line
 /// @param end_row          Last line index, inclusive
@@ -696,7 +696,7 @@ void nvim_buf_set_text(uint64_t channel_id, Buffer buffer, Integer start_row, In
 /// Prefer |nvim_buf_get_lines()| when retrieving entire lines.
 ///
 /// @param channel_id
-/// @param buffer     Buffer handle, or 0 for current buffer
+/// @param buffer     Buffer id, or 0 for current buffer
 /// @param start_row  First line index
 /// @param start_col  Starting column (byte offset) on first line
 /// @param end_row    Last line index, inclusive
@@ -790,7 +790,7 @@ end:
 /// Unlike |line2byte()|, throws error for out-of-bounds indexing.
 /// Returns -1 for unloaded buffer.
 ///
-/// @param buffer     Buffer handle, or 0 for current buffer
+/// @param buffer     Buffer id, or 0 for current buffer
 /// @param index      Line index
 /// @param[out] err   Error details, if any
 /// @return Integer byte offset, or -1 for unloaded buffer.
@@ -816,7 +816,7 @@ Integer nvim_buf_get_offset(Buffer buffer, Integer index, Error *err)
 
 /// Gets a buffer-scoped (b:) variable.
 ///
-/// @param buffer     Buffer handle, or 0 for current buffer
+/// @param buffer     Buffer id, or 0 for current buffer
 /// @param name       Variable name
 /// @param[out] err   Error details, if any
 /// @return Variable value
@@ -834,7 +834,7 @@ Object nvim_buf_get_var(Buffer buffer, String name, Arena *arena, Error *err)
 
 /// Gets a changed tick of a buffer
 ///
-/// @param[in]  buffer  Buffer handle, or 0 for current buffer
+/// @param[in]  buffer  Buffer id, or 0 for current buffer
 /// @param[out] err     Error details, if any
 ///
 /// @return `b:changedtick` value.
@@ -852,11 +852,11 @@ Integer nvim_buf_get_changedtick(Buffer buffer, Error *err)
 
 /// Gets a list of buffer-local |mapping| definitions.
 ///
-/// @param  buffer     Buffer handle, or 0 for current buffer
+/// @param  buffer     Buffer id, or 0 for current buffer
 /// @param  mode       Mode short-name ("n", "i", "v", ...)
 /// @param[out]  err   Error details, if any
 /// @returns Array of |maparg()|-like dictionaries describing mappings.
-///          The "buffer" key holds the associated buffer handle.
+///          The "buffer" key holds the associated buffer id.
 ArrayOf(Dict) nvim_buf_get_keymap(Buffer buffer, String mode, Arena *arena, Error *err)
   FUNC_API_SINCE(3)
 {
@@ -873,7 +873,7 @@ ArrayOf(Dict) nvim_buf_get_keymap(Buffer buffer, String mode, Arena *arena, Erro
 ///
 /// @see |nvim_set_keymap()|
 ///
-/// @param  buffer  Buffer handle, or 0 for current buffer
+/// @param  buffer  Buffer id, or 0 for current buffer
 void nvim_buf_set_keymap(uint64_t channel_id, Buffer buffer, String mode, String lhs, String rhs,
                          Dict(keymap) *opts, Error *err)
   FUNC_API_SINCE(6)
@@ -885,7 +885,7 @@ void nvim_buf_set_keymap(uint64_t channel_id, Buffer buffer, String mode, String
 ///
 /// @see |nvim_del_keymap()|
 ///
-/// @param  buffer  Buffer handle, or 0 for current buffer
+/// @param  buffer  Buffer id, or 0 for current buffer
 void nvim_buf_del_keymap(uint64_t channel_id, Buffer buffer, String mode, String lhs, Error *err)
   FUNC_API_SINCE(6)
 {
@@ -895,7 +895,7 @@ void nvim_buf_del_keymap(uint64_t channel_id, Buffer buffer, String mode, String
 
 /// Sets a buffer-scoped (b:) variable
 ///
-/// @param buffer     Buffer handle, or 0 for current buffer
+/// @param buffer     Buffer id, or 0 for current buffer
 /// @param name       Variable name
 /// @param value      Variable value
 /// @param[out] err   Error details, if any
@@ -913,7 +913,7 @@ void nvim_buf_set_var(Buffer buffer, String name, Object value, Error *err)
 
 /// Removes a buffer-scoped (b:) variable
 ///
-/// @param buffer     Buffer handle, or 0 for current buffer
+/// @param buffer     Buffer id, or 0 for current buffer
 /// @param name       Variable name
 /// @param[out] err   Error details, if any
 void nvim_buf_del_var(Buffer buffer, String name, Error *err)
@@ -930,7 +930,7 @@ void nvim_buf_del_var(Buffer buffer, String name, Error *err)
 
 /// Gets the full file name for the buffer
 ///
-/// @param buffer     Buffer handle, or 0 for current buffer
+/// @param buffer     Buffer id, or 0 for current buffer
 /// @param[out] err   Error details, if any
 /// @return Buffer name
 String nvim_buf_get_name(Buffer buffer, Error *err)
@@ -948,7 +948,7 @@ String nvim_buf_get_name(Buffer buffer, Error *err)
 
 /// Sets the full file name for a buffer, like |:file_f|
 ///
-/// @param buffer     Buffer handle, or 0 for current buffer
+/// @param buffer     Buffer id, or 0 for current buffer
 /// @param name       Buffer name
 /// @param[out] err   Error details, if any
 void nvim_buf_set_name(Buffer buffer, String name, Error *err)
@@ -992,7 +992,7 @@ void nvim_buf_set_name(Buffer buffer, String name, Error *err)
 /// Checks if a buffer is valid and loaded. See |api-buffer| for more info
 /// about unloaded buffers.
 ///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
 /// @return true if the buffer is valid and loaded, false otherwise.
 Boolean nvim_buf_is_loaded(Buffer buffer)
   FUNC_API_SINCE(5)
@@ -1005,7 +1005,7 @@ Boolean nvim_buf_is_loaded(Buffer buffer)
 
 /// Deletes the buffer. See |:bwipeout|
 ///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
 /// @param opts  Optional parameters. Keys:
 ///          - force:  Force deletion and ignore unsaved changes.
 ///          - unload: Unloaded only, do not delete. See |:bunload|
@@ -1040,7 +1040,7 @@ void nvim_buf_delete(Buffer buffer, Dict(buf_delete) *opts, Error *err)
 /// @note Even if a buffer is valid it may have been unloaded. See |api-buffer|
 /// for more info about unloaded buffers.
 ///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
 /// @return true if the buffer is valid, false otherwise.
 Boolean nvim_buf_is_valid(Buffer buffer)
   FUNC_API_SINCE(1)
@@ -1131,7 +1131,7 @@ Boolean nvim_buf_set_mark(Buffer buffer, String name, Integer line, Integer col,
 ///
 /// Marks are (1,0)-indexed. |api-indexing|
 ///
-/// @param buffer     Buffer handle, or 0 for current buffer
+/// @param buffer     Buffer id, or 0 for current buffer
 /// @param name       Mark name
 /// @param[out] err   Error details, if any
 /// @return (row, col) tuple, (0, 0) if the mark is not set, or is an
@@ -1187,7 +1187,7 @@ ArrayOf(Integer, 2) nvim_buf_get_mark(Buffer buffer, String name, Arena *arena,
 /// This is useful e.g. to call Vimscript functions that only work with the
 /// current buffer/window currently, like `jobstart(…, {'term': v:true})`.
 ///
-/// @param buffer     Buffer handle, or 0 for current buffer
+/// @param buffer     Buffer id, or 0 for current buffer
 /// @param fun        Function to call inside the buffer (currently Lua callable
 ///                   only)
 /// @param[out] err   Error details, if any

src/nvim/api/command.c

@@ -897,7 +897,7 @@ void nvim_del_user_command(String name, Error *err)
 
 /// Creates a buffer-local command |user-commands|.
 ///
-/// @param  buffer  Buffer handle, or 0 for current buffer.
+/// @param  buffer  Buffer id, or 0 for current buffer.
 /// @param[out] err Error details, if any.
 /// @see nvim_create_user_command
 void nvim_buf_create_user_command(uint64_t channel_id, Buffer buffer, String name, Object command,
@@ -920,7 +920,7 @@ void nvim_buf_create_user_command(uint64_t channel_id, Buffer buffer, String nam
 /// Only commands created with |:command-buffer| or
 /// |nvim_buf_create_user_command()| can be deleted with this function.
 ///
-/// @param  buffer  Buffer handle, or 0 for current buffer.
+/// @param  buffer  Buffer id, or 0 for current buffer.
 /// @param  name    Name of the command to delete.
 /// @param[out] err Error details, if any.
 void nvim_buf_del_user_command(Buffer buffer, String name, Error *err)
@@ -1178,7 +1178,7 @@ Dict nvim_get_commands(Dict(get_commands) *opts, Arena *arena, Error *err)
 
 /// Gets a map of buffer-local |user-commands|.
 ///
-/// @param  buffer  Buffer handle, or 0 for current buffer
+/// @param  buffer  Buffer id, or 0 for current buffer
 /// @param  opts  Optional parameters. Currently not used.
 /// @param[out]  err   Error details, if any.
 ///

src/nvim/api/deprecated.c

@@ -69,7 +69,7 @@ Object nvim_execute_lua(String code, Array args, Arena *arena, Error *err)
 ///
 /// @deprecated The buffer number now is equal to the object id
 ///
-/// @param buffer     Buffer handle, or 0 for current buffer
+/// @param buffer     Buffer id, or 0 for current buffer
 /// @param[out] err   Error details, if any
 /// @return Buffer number
 Integer nvim_buf_get_number(Buffer buffer, Error *err)
@@ -100,7 +100,7 @@ static uint32_t src2ns(Integer *src_id)
 ///
 /// @deprecated use |nvim_buf_clear_namespace()|.
 ///
-/// @param buffer     Buffer handle, or 0 for current buffer
+/// @param buffer     Buffer id, or 0 for current buffer
 /// @param ns_id      Namespace to clear, or -1 to clear all.
 /// @param line_start Start of range of lines to clear
 /// @param line_end   End of range of lines to clear (exclusive) or -1 to clear
@@ -131,7 +131,7 @@ void nvim_buf_clear_highlight(Buffer buffer, Integer ns_id, Integer line_start,
 /// supported for backwards compatibility, new code should use
 /// |nvim_create_namespace()| to create a new empty namespace.
 ///
-/// @param buffer     Buffer handle, or 0 for current buffer
+/// @param buffer     Buffer id, or 0 for current buffer
 /// @param ns_id      namespace to use or -1 for ungrouped highlight
 /// @param hl_group   Name of the highlight group to use
 /// @param line       Line to highlight (zero-indexed)
@@ -207,7 +207,7 @@ Integer nvim_buf_add_highlight(Buffer buffer, Integer ns_id, String hl_group, In
 /// As a shorthand, `ns_id = 0` can be used to create a new namespace for the
 /// virtual text, the allocated id is then returned.
 ///
-/// @param buffer     Buffer handle, or 0 for current buffer
+/// @param buffer     Buffer id, or 0 for current buffer
 /// @param src_id     Namespace to use or 0 to create a namespace,
 ///                   or -1 for a ungrouped annotation
 /// @param line       Line to annotate with virtual text (zero-indexed)
@@ -309,7 +309,7 @@ Dict nvim_get_hl_by_name(String name, Boolean rgb, Arena *arena, Error *err)
 ///
 /// @deprecated use nvim_buf_set_lines(buffer, lnum, lnum, true, lines)
 ///
-/// @param buffer     Buffer handle
+/// @param buffer     Buffer id
 /// @param lnum       Insert the lines after `lnum`. If negative, appends to
 ///                   the end of the buffer.
 /// @param lines      Array of lines
@@ -330,7 +330,7 @@ void buffer_insert(Buffer buffer, Integer lnum, ArrayOf(String) lines, Arena *ar
 ///             for negative indices use
 ///                 "nvim_buf_get_lines(buffer, index-1, index, true)"
 ///
-/// @param buffer   Buffer handle
+/// @param buffer   Buffer id
 /// @param index    Line index
 /// @param[out] err Error details, if any
 /// @return Line string
@@ -357,7 +357,7 @@ String buffer_get_line(Buffer buffer, Integer index, Arena *arena, Error *err)
 ///             for negative indices use
 ///                 "nvim_buf_set_lines(buffer, index-1, index, true, [line])"
 ///
-/// @param buffer   Buffer handle
+/// @param buffer   Buffer id
 /// @param index    Line index
 /// @param line     Contents of the new line
 /// @param[out] err Error details, if any
@@ -377,7 +377,7 @@ void buffer_set_line(Buffer buffer, Integer index, String line, Arena *arena, Er
 ///                 "nvim_buf_set_lines(buffer, index, index+1, true, [])"
 ///             for negative indices use
 ///                 "nvim_buf_set_lines(buffer, index-1, index, true, [])"
-/// @param buffer   buffer handle
+/// @param buffer   buffer id
 /// @param index    line index
 /// @param[out] err Error details, if any
 void buffer_del_line(Buffer buffer, Integer index, Arena *arena, Error *err)
@@ -394,7 +394,7 @@ void buffer_del_line(Buffer buffer, Integer index, Arena *arena, Error *err)
 ///             where newstart = start + int(not include_start) - int(start < 0)
 ///                   newend = end + int(include_end) - int(end < 0)
 ///                   int(bool) = 1 if bool is true else 0
-/// @param buffer         Buffer handle
+/// @param buffer         Buffer id
 /// @param start          First line index
 /// @param end            Last line index
 /// @param include_start  True if the slice includes the `start` parameter
@@ -422,7 +422,7 @@ ArrayOf(String) buffer_get_line_slice(Buffer buffer,
 ///                   newend = end + int(include_end) + int(end < 0)
 ///                   int(bool) = 1 if bool is true else 0
 ///
-/// @param buffer         Buffer handle, or 0 for current buffer
+/// @param buffer         Buffer id, or 0 for current buffer
 /// @param start          First line index
 /// @param end            Last line index
 /// @param include_start  True if the slice includes the `start` parameter
@@ -444,7 +444,7 @@ void buffer_set_line_slice(Buffer buffer, Integer start, Integer end, Boolean in
 ///
 /// @deprecated
 ///
-/// @param buffer     Buffer handle, or 0 for current buffer
+/// @param buffer     Buffer id, or 0 for current buffer
 /// @param name       Variable name
 /// @param value      Variable value
 /// @param[out] err   Error details, if any
@@ -468,7 +468,7 @@ Object buffer_set_var(Buffer buffer, String name, Object value, Arena *arena, Er
 ///
 /// @deprecated
 ///
-/// @param buffer     Buffer handle, or 0 for current buffer
+/// @param buffer     Buffer id, or 0 for current buffer
 /// @param name       Variable name
 /// @param[out] err   Error details, if any
 /// @return Old value
@@ -641,7 +641,7 @@ Object nvim_get_option(String name, Error *err)
 /// Gets a buffer option value
 ///
 /// @deprecated
-/// @param buffer     Buffer handle, or 0 for current buffer
+/// @param buffer     Buffer id, or 0 for current buffer
 /// @param name       Option name
 /// @param[out] err   Error details, if any
 /// @return Option value
@@ -664,7 +664,7 @@ Object nvim_buf_get_option(Buffer buffer, String name, Error *err)
 ///
 /// @deprecated
 /// @param channel_id
-/// @param buffer     Buffer handle, or 0 for current buffer
+/// @param buffer     Buffer id, or 0 for current buffer
 /// @param name       Option name
 /// @param value      Option value
 /// @param[out] err   Error details, if any

src/nvim/api/extmark.c

@@ -192,7 +192,7 @@ static Array extmark_to_array(MTPair extmark, bool id, bool add_dict, bool hl_na
 
 /// Gets the position (0-indexed) of an |extmark|.
 ///
-/// @param buffer  Buffer handle, or 0 for current buffer
+/// @param buffer  Buffer id, or 0 for current buffer
 /// @param ns_id  Namespace id from |nvim_create_namespace()|
 /// @param id  Extmark id
 /// @param opts  Optional parameters. Keys:
@@ -269,7 +269,7 @@ ArrayOf(Integer) nvim_buf_get_extmark_by_id(Buffer buffer, Integer ns_id,
 /// vim.print(ms)
 /// ```
 ///
-/// @param buffer  Buffer handle, or 0 for current buffer
+/// @param buffer  Buffer id, or 0 for current buffer
 /// @param ns_id  Namespace id from |nvim_create_namespace()| or -1 for all namespaces
 /// @param start  Start of range: a 0-indexed (row, col) or valid extmark id
 /// (whose position defines the bound). |api-indexing|
@@ -374,7 +374,7 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start, Object e
 /// An earlier end position is not an error, but then it behaves like an empty
 /// range (no highlighting).
 ///
-/// @param buffer  Buffer handle, or 0 for current buffer
+/// @param buffer  Buffer id, or 0 for current buffer
 /// @param ns_id  Namespace id from |nvim_create_namespace()|
 /// @param line  Line where to place the mark, 0-based. |api-indexing|
 /// @param col  Column where to place the mark, 0-based. |api-indexing|
@@ -922,7 +922,7 @@ error:
 
 /// Removes an |extmark|.
 ///
-/// @param buffer Buffer handle, or 0 for current buffer
+/// @param buffer Buffer id, or 0 for current buffer
 /// @param ns_id Namespace id from |nvim_create_namespace()|
 /// @param id Extmark id
 /// @param[out] err   Error details, if any
@@ -948,7 +948,7 @@ Boolean nvim_buf_del_extmark(Buffer buffer, Integer ns_id, Integer id, Error *er
 /// Lines are 0-indexed. |api-indexing|  To clear the namespace in the entire
 /// buffer, specify line_start=0 and line_end=-1.
 ///
-/// @param buffer     Buffer handle, or 0 for current buffer
+/// @param buffer     Buffer id, or 0 for current buffer
 /// @param ns_id      Namespace to clear, or -1 to clear all namespaces.
 /// @param line_start Start of range of lines to clear
 /// @param line_end   End of range of lines to clear (exclusive) or -1 to clear

src/nvim/api/private/helpers.c

@@ -472,7 +472,7 @@ int64_t normalize_index(buf_T *buf, int64_t index, bool end_exclusive, bool *oob
 
 /// Returns a substring of a buffer line
 ///
-/// @param buf          Buffer handle
+/// @param buf          Buffer id
 /// @param lnum         Line number (1-based)
 /// @param start_col    Starting byte offset into line (0-based)
 /// @param end_col      Ending byte offset into line (0-based, exclusive)

src/nvim/api/vim.c

@@ -790,12 +790,12 @@ error:
   hl_msg_free(hl_msg);
 }
 
-/// Gets the current list of buffer handles
+/// Gets the current list of buffers.
 ///
 /// Includes unlisted (unloaded/deleted) buffers, like `:ls!`.
 /// Use |nvim_buf_is_loaded()| to check if a buffer is loaded.
 ///
-/// @return List of buffer handles
+/// @return List of buffer ids
 ArrayOf(Buffer) nvim_list_bufs(Arena *arena)
   FUNC_API_SINCE(1)
 {
@@ -816,7 +816,7 @@ ArrayOf(Buffer) nvim_list_bufs(Arena *arena)
 
 /// Gets the current buffer.
 ///
-/// @return Buffer handle
+/// @return Buffer id
 Buffer nvim_get_current_buf(void)
   FUNC_API_SINCE(1)
 {
@@ -825,7 +825,7 @@ Buffer nvim_get_current_buf(void)
 
 /// Sets the current window's buffer to `buffer`.
 ///
-/// @param buffer   Buffer handle
+/// @param buffer   Buffer id
 /// @param[out] err Error details, if any
 void nvim_set_current_buf(Buffer buffer, Error *err)
   FUNC_API_SINCE(1)
@@ -842,7 +842,7 @@ void nvim_set_current_buf(Buffer buffer, Error *err)
   });
 }
 
-/// Gets the current list of window handles.
+/// Gets the current list of all |window-ID|s in all tabpages.
 ///
 /// @return List of |window-ID|s
 ArrayOf(Window) nvim_list_wins(Arena *arena)
@@ -897,7 +897,7 @@ void nvim_set_current_win(Window window, Error *err)
 /// @param scratch Creates a "throwaway" |scratch-buffer| for temporary work
 ///                (always 'nomodified'). Also sets 'nomodeline' on the buffer.
 /// @param[out] err Error details, if any
-/// @return Buffer handle, or 0 on error
+/// @return Buffer id, or 0 on error
 ///
 /// @see buf_open_scratch
 Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err)

src/nvim/api/window.c

@@ -34,7 +34,7 @@
 ///
 /// @param window   |window-ID|, or 0 for current window
 /// @param[out] err Error details, if any
-/// @return Buffer handle
+/// @return Buffer id
 Buffer nvim_win_get_buf(Window window, Error *err)
   FUNC_API_SINCE(1)
 {
@@ -50,7 +50,7 @@ Buffer nvim_win_get_buf(Window window, Error *err)
 /// Sets the current buffer in a window, without side effects
 ///
 /// @param window   |window-ID|, or 0 for current window
-/// @param buffer   Buffer handle
+/// @param buffer   Buffer id
 /// @param[out] err Error details, if any
 void nvim_win_set_buf(Window window, Buffer buffer, Error *err)
   FUNC_API_SINCE(5)