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