Merge #32810 docs

1 files changed, 32 insertions, 33 deletions

diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index aa349790b3..f8ebf4b838 100644
--- a/src/nvim/api/buffer.c
+++ b/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.
@@ -238,8 +238,10 @@ Boolean nvim_buf_detach(uint64_t channel_id, Buffer buffer, Error *err)
 /// Out-of-bounds indices are clamped to the nearest valid value, unless
 /// `strict_indexing` is set.
 ///
+/// @see |nvim_buf_get_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.
@@ -294,7 +296,7 @@ ArrayOf(String) nvim_buf_get_lines(uint64_t channel_id,
 ///
 /// Indexing is zero-based, end-exclusive. Negative indices are interpreted
 /// as length+1+index: -1 refers to the index past the end. So to change
-/// or delete the last element use start=-2 and end=-1.
+/// or delete the last line use start=-2 and end=-1.
 ///
 /// To insert lines at a given index, set `start` and `end` to the same index.
 /// To delete a range of lines, set `replacement` to an empty array.
@@ -305,7 +307,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 +465,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
@@ -685,10 +687,7 @@ void nvim_buf_set_text(uint64_t channel_id, Buffer buffer, Integer start_row, In
   });
 }
 
-/// Gets a range from the buffer.
-///
-/// This differs from |nvim_buf_get_lines()| in that it allows retrieving only
-/// portions of a line.
+/// Gets a range from the buffer (may be partial lines, unlike |nvim_buf_get_lines()|).
 ///
 /// Indexing is zero-based. Row indices are end-inclusive, and column indices
 /// are end-exclusive.
@@ -696,7 +695,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 +789,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 +815,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 +833,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 +851,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 +872,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 +884,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 +894,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 +912,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 +929,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 +947,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 +991,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 +1004,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 +1039,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 +1130,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 +1186,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