doc: API

2 files changed, 37 insertions, 18 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 712a8878ba..e16b6b7e75 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -638,7 +638,7 @@ nvim_set_client_info({name}, {version}, {type}, {methods},
                                   Clients might define their own keys, but the
                                   following are suggested:   "website" Website
                                   of client (for instance github repository)
-                                  "license" Informal descripton of the
+                                  "license" Informal description of the
                                   license, such as "Apache 2", "GPLv3" or
                                   "MIT"  "logo" URI or path to image,
                                   preferably small logo or icon. .png or .svg
@@ -862,8 +862,7 @@ nvim_buf_line_count({buffer})                          *nvim_buf_line_count()*
                     {buffer}  Buffer handle
 
                 Return: ~
-                    Line count, or `0` if the buffer has been unloaded (see
-                    |api-buffer|).
+                    Line count, or 0 for unloaded buffer. |api-buffer|
 
 nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
                 Activate updates from this buffer to the current channel.
@@ -912,8 +911,7 @@ nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})
                                        error.
 
                 Return: ~
-                    Array of lines. If the buffer has been unloaded then an
-                    empty array will be returned instead. (See |api-buffer|.)
+                    Array of lines, or empty array for unloaded buffer.
 
                                                         *nvim_buf_set_lines()*
 nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing},
@@ -940,6 +938,25 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing},
                                        error.
                     {replacement}      Array of lines to use as replacement
 
+nvim_buf_get_offset({buffer}, {index})                 *nvim_buf_get_offset()*
+                Returns the byte offset for a line.
+
+                Line 1 (index=0) has offset 0. UTF-8 bytes are counted. EOL is
+                one byte. 'fileformat' and 'fileencoding' are ignored. The
+                line index just after the last line gives the total byte-count
+                of the buffer. A final EOL byte is counted if it would be
+                written, see 'eol'.
+
+                Unlike |line2byte()|, throws error for out-of-bounds indexing.
+                Returns -1 for unloaded buffer.
+
+                Parameters: ~
+                    {buffer}  Buffer handle
+                    {index}   Line index
+
+                Return: ~
+                    Integer byte offset, or -1 for unloaded buffer.
+
 nvim_buf_get_var({buffer}, {name})                        *nvim_buf_get_var()*
                 Gets a buffer-scoped (b:) variable.
 
@@ -1106,8 +1123,8 @@ nvim_buf_add_highlight({buffer}, {src_id}, {hl_group}, {line},
 
                                                   *nvim_buf_clear_highlight()*
 nvim_buf_clear_highlight({buffer}, {src_id}, {line_start}, {line_end})
-                Clears highlights from a given source group and a range of
-                lines
+                Clears highlights and virtual text from a given source id and
+                range of lines
 
                 To clear a source group in the entire buffer, pass in 0 and -1
                 to line_start and line_end respectively.
@@ -1132,6 +1149,10 @@ nvim_buf_set_virtual_text({buffer}, {src_id}, {line}, {chunks},
                 the right of the ordinary text, this will contain the |lcs-
                 eol| char if set, otherwise just be a space.
 
+                The same src_id can be used for both virtual text and
+                highlights added by nvim_buf_add_highlight. Virtual text is
+                cleared using nvim_buf_clear_highlight.
+
                 Parameters: ~
                     {buffer}  Buffer handle
                     {src_id}  Source group to use or 0 to use a new group, or
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 39330690e8..487a912882 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -51,8 +51,7 @@
 ///
 /// @param buffer   Buffer handle
 /// @param[out] err Error details, if any
-/// @return Line count, or \`0` if the buffer has been unloaded (see
-///         |api-buffer|).
+/// @return Line count, or 0 for unloaded buffer. |api-buffer|
 Integer nvim_buf_line_count(Buffer buffer, Error *err)
   FUNC_API_SINCE(1)
 {
@@ -227,8 +226,7 @@ ArrayOf(String) buffer_get_line_slice(Buffer buffer,
 /// @param end              Last line index (exclusive)
 /// @param strict_indexing  Whether out-of-bounds should be an error.
 /// @param[out] err         Error details, if any
-/// @return Array of lines. If the buffer has been unloaded then an empty array
-///                         will be returned instead. (See |api-buffer|.)
+/// @return Array of lines, or empty array for unloaded buffer.
 ArrayOf(String) nvim_buf_get_lines(uint64_t channel_id,
                                    Buffer buffer,
                                    Integer start,
@@ -491,12 +489,12 @@ end:
   try_end(err);
 }
 
-/// Return the byte offset for a line.
-//
-/// The first line returns 0. UTF-8 bytes are counted, and EOL counts as one
-/// byte. 'fileformat' and 'fileencoding' are ignored. Sending in the index
-/// just below the last line gives the total byte count for the entire buffer.
-/// A final EOL is included if it would be written, see 'eol'.
+/// Returns the byte offset for a line.
+///
+/// Line 1 (index=0) has offset 0. UTF-8 bytes are counted. EOL is one byte.
+/// 'fileformat' and 'fileencoding' are ignored. The line index just after the
+/// last line gives the total byte-count of the buffer. A final EOL byte is
+/// counted if it would be written, see 'eol'.
 ///
 /// Unlike |line2byte()|, throws error for out-of-bounds indexing.
 /// Returns -1 for unloaded buffer.
@@ -504,7 +502,7 @@ end:
 /// @param buffer     Buffer handle
 /// @param index      Line index
 /// @param[out] err   Error details, if any
-/// @return Integer   Byte offset
+/// @return Integer byte offset, or -1 for unloaded buffer.
 Integer nvim_buf_get_offset(Buffer buffer, Integer index, Error *err)
   FUNC_API_SINCE(5)
 {