From b96730bc3bc71e03004b9720bcd0ac67a2a7bb85 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 5 Nov 2018 03:50:22 +0100 Subject: [PATCH] doc: API --- runtime/doc/api.txt | 35 ++++++++++++++++++++++++++++------- src/nvim/api/buffer.c | 20 +++++++++----------- 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) {