aboutsummaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
Diffstat (limited to 'src')
-rw-r--r--src/nvim/api/buffer.c206
-rw-r--r--src/nvim/api/tabpage.c68
-rw-r--r--src/nvim/api/vim.c193
-rw-r--r--src/nvim/api/window.c120
4 files changed, 296 insertions, 291 deletions
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 09d717bff6..eaaae943d2 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -28,9 +28,9 @@
/// Gets the buffer line count
///
-/// @param buffer The buffer handle
-/// @param[out] err Details of an error that may have occurred
-/// @return The line count
+/// @param buffer Buffer handle
+/// @param[out] err Error details, if any
+/// @return Line count
Integer nvim_buf_line_count(Buffer buffer, Error *err)
{
buf_T *buf = find_buffer_by_handle(buffer, err);
@@ -50,10 +50,10 @@ Integer nvim_buf_line_count(Buffer buffer, Error *err)
/// for negative indices use
/// "nvim_buf_get_lines(buffer, index-1, index, true)"
///
-/// @param buffer The buffer handle
-/// @param index The line index
-/// @param[out] err Details of an error that may have occurred
-/// @return The line string
+/// @param buffer Buffer handle
+/// @param index Line index
+/// @param[out] err Error details, if any
+/// @return Line string
String buffer_get_line(Buffer buffer, Integer index, Error *err)
{
String rv = { .size = 0 };
@@ -78,10 +78,10 @@ String buffer_get_line(Buffer buffer, Integer index, Error *err)
/// for negative indices use
/// "nvim_buf_set_lines(buffer, index-1, index, true, [line])"
///
-/// @param buffer The buffer handle
-/// @param index The line index
-/// @param line The new line.
-/// @param[out] err Details of an error that may have occurred
+/// @param buffer Buffer handle
+/// @param index Line index
+/// @param line Contents of the new line
+/// @param[out] err Error details, if any
void buffer_set_line(Buffer buffer, Integer index, String line, Error *err)
{
Object l = STRING_OBJ(line);
@@ -97,9 +97,9 @@ void buffer_set_line(Buffer buffer, Integer index, String line, Error *err)
/// "nvim_buf_set_lines(buffer, index, index+1, true, [])"
/// for negative indices use
/// "nvim_buf_set_lines(buffer, index-1, index, true, [])"
-/// @param buffer The buffer handle
-/// @param index The line index
-/// @param[out] err Details of an error that may have occurred
+/// @param buffer buffer handle
+/// @param index line index
+/// @param[out] err Error details, if any
void buffer_del_line(Buffer buffer, Integer index, Error *err)
{
Array array = ARRAY_DICT_INIT;
@@ -113,13 +113,13 @@ void buffer_del_line(Buffer buffer, Integer index, 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 The buffer handle
-/// @param start The first line index
-/// @param end The last line index
-/// @param include_start True if the slice includes the `start` parameter
-/// @param include_end True if the slice includes the `end` parameter
-/// @param[out] err Details of an error that may have occurred
-/// @return An array of lines
+/// @param buffer Buffer handle
+/// @param start First line index
+/// @param end Last line index
+/// @param include_start True if the slice includes the `start` parameter
+/// @param include_end True if the slice includes the `end` parameter
+/// @param[out] err Error details, if any
+/// @return Array of lines
ArrayOf(String) buffer_get_line_slice(Buffer buffer,
Integer start,
Integer end,
@@ -142,12 +142,12 @@ ArrayOf(String) buffer_get_line_slice(Buffer buffer,
/// Out-of-bounds indices are clamped to the nearest valid value, unless
/// `strict_indexing` is set.
///
-/// @param buffer The buffer handle
-/// @param start The first line index
-/// @param end The last line index (exclusive)
-/// @param strict_indexing whether out-of-bounds should be an error.
-/// @param[out] err Details of an error that may have occurred
-/// @return An array of lines
+/// @param buffer Buffer handle
+/// @param start First line index
+/// @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
ArrayOf(String) nvim_buf_get_lines(uint64_t channel_id,
Buffer buffer,
Integer start,
@@ -219,14 +219,14 @@ end:
/// newend = end + int(include_end) + int(end < 0)
/// int(bool) = 1 if bool is true else 0
///
-/// @param buffer The buffer handle
-/// @param start The first line index
-/// @param end The last line index
-/// @param include_start True if the slice includes the `start` parameter
-/// @param include_end True if the slice includes the `end` parameter
-/// @param replacement An array of lines to use as replacement(A 0-length
-// array will simply delete the line range)
-/// @param[out] err Details of an error that may have occurred
+/// @param buffer Buffer handle
+/// @param start First line index
+/// @param end Last line index
+/// @param include_start True if the slice includes the `start` parameter
+/// @param include_end True if the slice includes the `end` parameter
+/// @param replacement Array of lines to use as replacement (0-length
+// array will delete the line range)
+/// @param[out] err Error details, if any
void buffer_set_line_slice(Buffer buffer,
Integer start,
Integer end,
@@ -253,12 +253,12 @@ void buffer_set_line_slice(Buffer buffer,
/// Out-of-bounds indices are clamped to the nearest valid value, unless
/// `strict_indexing` is set.
///
-/// @param buffer The buffer handle
-/// @param start The first line index
-/// @param end The last line index (exclusive)
-/// @param strict_indexing whether out-of-bounds should be an error.
-/// @param replacement An array of lines to use as replacement
-/// @param[out] err Details of an error that may have occurred
+/// @param buffer Buffer handle
+/// @param start First line index
+/// @param end Last line index (exclusive)
+/// @param strict_indexing Whether out-of-bounds should be an error.
+/// @param replacement Array of lines to use as replacement
+/// @param[out] err Error details, if any
void nvim_buf_set_lines(uint64_t channel_id,
Buffer buffer,
Integer start,
@@ -411,10 +411,10 @@ end:
/// Gets a buffer-scoped (b:) variable.
///
-/// @param buffer The buffer handle
-/// @param name The variable name
-/// @param[out] err Details of an error that may have occurred
-/// @return The variable value
+/// @param buffer Buffer handle
+/// @param name Variable name
+/// @param[out] err Error details, if any
+/// @return Variable value
Object nvim_buf_get_var(Buffer buffer, String name, Error *err)
{
buf_T *buf = find_buffer_by_handle(buffer, err);
@@ -428,10 +428,10 @@ Object nvim_buf_get_var(Buffer buffer, String name, Error *err)
/// Sets a buffer-scoped (b:) variable
///
-/// @param buffer The buffer handle
-/// @param name The variable name
-/// @param value The variable value
-/// @param[out] err Details of an error that may have occurred
+/// @param buffer Buffer handle
+/// @param name Variable name
+/// @param value Variable value
+/// @param[out] err Error details, if any
void nvim_buf_set_var(Buffer buffer, String name, Object value, Error *err)
{
buf_T *buf = find_buffer_by_handle(buffer, err);
@@ -445,9 +445,9 @@ void nvim_buf_set_var(Buffer buffer, String name, Object value, Error *err)
/// Removes a buffer-scoped (b:) variable
///
-/// @param buffer The buffer handle
-/// @param name The variable name
-/// @param[out] err Details of an error that may have occurred
+/// @param buffer Buffer handle
+/// @param name Variable name
+/// @param[out] err Error details, if any
void nvim_buf_del_var(Buffer buffer, String name, Error *err)
{
buf_T *buf = find_buffer_by_handle(buffer, err);
@@ -463,11 +463,11 @@ void nvim_buf_del_var(Buffer buffer, String name, Error *err)
///
/// @deprecated
///
-/// @param buffer The buffer handle
-/// @param name The variable name
-/// @param value The variable value
-/// @param[out] err Details of an error that may have occurred
-/// @return The old value or nil if there was no previous value.
+/// @param buffer Buffer handle
+/// @param name Variable name
+/// @param value Variable value
+/// @param[out] err Error details, if any
+/// @return Old value or nil if there was no previous value.
///
/// @warning It may return nil if there was no previous value
/// or if previous value was `v:null`.
@@ -486,10 +486,10 @@ Object buffer_set_var(Buffer buffer, String name, Object value, Error *err)
///
/// @deprecated
///
-/// @param buffer The buffer handle
-/// @param name The variable name
-/// @param[out] err Details of an error that may have occurred
-/// @return The old value
+/// @param buffer Buffer handle
+/// @param name Variable name
+/// @param[out] err Error details, if any
+/// @return Old value
Object buffer_del_var(Buffer buffer, String name, Error *err)
{
buf_T *buf = find_buffer_by_handle(buffer, err);
@@ -504,10 +504,10 @@ Object buffer_del_var(Buffer buffer, String name, Error *err)
/// Gets a buffer option value
///
-/// @param buffer The buffer handle
-/// @param name The option name
-/// @param[out] err Details of an error that may have occurred
-/// @return The option value
+/// @param buffer Buffer handle
+/// @param name Option name
+/// @param[out] err Error details, if any
+/// @return Option value
Object nvim_buf_get_option(Buffer buffer, String name, Error *err)
{
buf_T *buf = find_buffer_by_handle(buffer, err);
@@ -519,13 +519,13 @@ Object nvim_buf_get_option(Buffer buffer, String name, Error *err)
return get_option_from(buf, SREQ_BUF, name, err);
}
-/// Sets a buffer option value. Passing 'nil' as value deletes the option(only
+/// Sets a buffer option value. Passing 'nil' as value deletes the option (only
/// works if there's a global fallback)
///
-/// @param buffer The buffer handle
-/// @param name The option name
-/// @param value The option value
-/// @param[out] err Details of an error that may have occurred
+/// @param buffer Buffer handle
+/// @param name Option name
+/// @param value Option value
+/// @param[out] err Error details, if any
void nvim_buf_set_option(Buffer buffer, String name, Object value, Error *err)
{
buf_T *buf = find_buffer_by_handle(buffer, err);
@@ -539,9 +539,9 @@ void nvim_buf_set_option(Buffer buffer, String name, Object value, Error *err)
/// Gets the buffer number
///
-/// @param buffer The buffer handle
-/// @param[out] err Details of an error that may have occurred
-/// @return The buffer number
+/// @param buffer Buffer handle
+/// @param[out] err Error details, if any
+/// @return Buffer number
Integer nvim_buf_get_number(Buffer buffer, Error *err)
{
Integer rv = 0;
@@ -556,9 +556,9 @@ Integer nvim_buf_get_number(Buffer buffer, Error *err)
/// Gets the full file name for the buffer
///
-/// @param buffer The buffer handle
-/// @param[out] err Details of an error that may have occurred
-/// @return The buffer name
+/// @param buffer Buffer handle
+/// @param[out] err Error details, if any
+/// @return Buffer name
String nvim_buf_get_name(Buffer buffer, Error *err)
{
String rv = STRING_INIT;
@@ -573,9 +573,9 @@ String nvim_buf_get_name(Buffer buffer, Error *err)
/// Sets the full file name for a buffer
///
-/// @param buffer The buffer handle
-/// @param name The buffer name
-/// @param[out] err Details of an error that may have occurred
+/// @param buffer Buffer handle
+/// @param name Buffer name
+/// @param[out] err Error details, if any
void nvim_buf_set_name(Buffer buffer, String name, Error *err)
{
buf_T *buf = find_buffer_by_handle(buffer, err);
@@ -603,7 +603,7 @@ void nvim_buf_set_name(Buffer buffer, String name, Error *err)
/// Checks if a buffer is valid
///
-/// @param buffer The buffer handle
+/// @param buffer Buffer handle
/// @return true if the buffer is valid, false otherwise
Boolean nvim_buf_is_valid(Buffer buffer)
{
@@ -615,11 +615,11 @@ Boolean nvim_buf_is_valid(Buffer buffer)
///
/// @deprecated use nvim_buf_set_lines(buffer, lnum, lnum, true, lines)
///
-/// @param buffer The buffer handle
-/// @param lnum Insert the lines after `lnum`. If negative, it will append
-/// to the end of the buffer.
-/// @param lines An array of lines
-/// @param[out] err Details of an error that may have occurred
+/// @param buffer Buffer handle
+/// @param lnum Insert the lines after `lnum`. If negative, appends to
+/// the end of the buffer.
+/// @param lines Array of lines
+/// @param[out] err Error details, if any
void buffer_insert(Buffer buffer,
Integer lnum,
ArrayOf(String) lines,
@@ -632,10 +632,10 @@ void buffer_insert(Buffer buffer,
/// Return a tuple (row,col) representing the position of the named mark
///
-/// @param buffer The buffer handle
-/// @param name The mark's name
-/// @param[out] err Details of an error that may have occurred
-/// @return The (row, col) tuple
+/// @param buffer Buffer handle
+/// @param name Mark name
+/// @param[out] err Error details, if any
+/// @return (row, col) tuple
ArrayOf(Integer, 2) nvim_buf_get_mark(Buffer buffer, String name, Error *err)
{
Array rv = ARRAY_DICT_INIT;
@@ -694,15 +694,15 @@ ArrayOf(Integer, 2) nvim_buf_get_mark(Buffer buffer, String name, Error *err)
/// request an unique src_id at initialization, and later asynchronously add and
/// clear highlights in response to buffer changes.
///
-/// @param buffer The buffer handle
-/// @param src_id Source group to use or 0 to use a new group,
-/// or -1 for ungrouped highlight
-/// @param hl_group Name of the highlight group to use
-/// @param line The line to highlight
-/// @param col_start Start of range of columns to highlight
-/// @param col_end End of range of columns to highlight,
-/// or -1 to highlight to end of line
-/// @param[out] err Details of an error that may have occurred
+/// @param buffer Buffer handle
+/// @param src_id Source group to use or 0 to use a new group,
+/// or -1 for ungrouped highlight
+/// @param hl_group Name of the highlight group to use
+/// @param line Line to highlight
+/// @param col_start Start of range of columns to highlight
+/// @param col_end End of range of columns to highlight,
+/// or -1 to highlight to end of line
+/// @param[out] err Error details, if any
/// @return The src_id that was used
Integer nvim_buf_add_highlight(Buffer buffer,
Integer src_id,
@@ -740,12 +740,12 @@ Integer nvim_buf_add_highlight(Buffer buffer,
/// To clear a source group in the entire buffer, pass in 1 and -1 to
/// line_start and line_end respectively.
///
-/// @param buffer The buffer handle
-/// @param src_id Highlight source group to clear, or -1 to clear all groups.
+/// @param buffer Buffer handle
+/// @param src_id Highlight source group 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 to end of file.
-/// @param[out] err Details of an error that may have occurred
+/// @param line_end End of range of lines to clear (exclusive) or -1 to clear
+/// to end of file.
+/// @param[out] err Error details, if any
void nvim_buf_clear_highlight(Buffer buffer,
Integer src_id,
Integer line_start,
diff --git a/src/nvim/api/tabpage.c b/src/nvim/api/tabpage.c
index fa00988ae3..9e61ec1871 100644
--- a/src/nvim/api/tabpage.c
+++ b/src/nvim/api/tabpage.c
@@ -11,9 +11,9 @@
/// Gets the windows in a tabpage
///
-/// @param tabpage The tabpage
-/// @param[out] err Details of an error that may have occurred
-/// @return The windows in `tabpage`
+/// @param tabpage Tabpage
+/// @param[out] err Error details, if any
+/// @return List of windows in `tabpage`
ArrayOf(Window) nvim_tabpage_list_wins(Tabpage tabpage, Error *err)
{
Array rv = ARRAY_DICT_INIT;
@@ -39,10 +39,10 @@ ArrayOf(Window) nvim_tabpage_list_wins(Tabpage tabpage, Error *err)
/// Gets a tab-scoped (t:) variable
///
-/// @param tabpage The tab page handle
-/// @param name The variable name
-/// @param[out] err Details of an error that may have occurred
-/// @return The variable value
+/// @param tabpage Tabpage handle
+/// @param name Variable name
+/// @param[out] err Error details, if any
+/// @return Variable value
Object nvim_tabpage_get_var(Tabpage tabpage, String name, Error *err)
{
tabpage_T *tab = find_tab_by_handle(tabpage, err);
@@ -56,10 +56,10 @@ Object nvim_tabpage_get_var(Tabpage tabpage, String name, Error *err)
/// Sets a tab-scoped (t:) variable
///
-/// @param tabpage handle
-/// @param name The variable name
-/// @param value The variable value
-/// @param[out] err Details of an error that may have occurred
+/// @param tabpage Tabpage handle
+/// @param name Variable name
+/// @param value Variable value
+/// @param[out] err Error details, if any
void nvim_tabpage_set_var(Tabpage tabpage,
String name,
Object value,
@@ -76,9 +76,9 @@ void nvim_tabpage_set_var(Tabpage tabpage,
/// Removes a tab-scoped (t:) variable
///
-/// @param tabpage handle
-/// @param name The variable name
-/// @param[out] err Details of an error that may have occurred
+/// @param tabpage Tabpage handle
+/// @param name Variable name
+/// @param[out] err Error details, if any
void nvim_tabpage_del_var(Tabpage tabpage, String name, Error *err)
{
tabpage_T *tab = find_tab_by_handle(tabpage, err);
@@ -94,11 +94,11 @@ void nvim_tabpage_del_var(Tabpage tabpage, String name, Error *err)
///
/// @deprecated
///
-/// @param tabpage handle
-/// @param name The variable name
-/// @param value The variable value
-/// @param[out] err Details of an error that may have occurred
-/// @return The old value or nil if there was no previous value.
+/// @param tabpage Tabpage handle
+/// @param name Variable name
+/// @param value Variable value
+/// @param[out] err Error details, if any
+/// @return Old value or nil if there was no previous value.
///
/// @warning It may return nil if there was no previous value
/// or if previous value was `v:null`.
@@ -117,10 +117,10 @@ Object tabpage_set_var(Tabpage tabpage, String name, Object value, Error *err)
///
/// @deprecated
///
-/// @param tabpage handle
-/// @param name The variable name
-/// @param[out] err Details of an error that may have occurred
-/// @return The old value
+/// @param tabpage Tabpage handle
+/// @param name Variable name
+/// @param[out] err Error details, if any
+/// @return Old value
Object tabpage_del_var(Tabpage tabpage, String name, Error *err)
{
tabpage_T *tab = find_tab_by_handle(tabpage, err);
@@ -132,11 +132,11 @@ Object tabpage_del_var(Tabpage tabpage, String name, Error *err)
return dict_set_value(tab->tp_vars, name, NIL, true, true, err);
}
-/// Gets the current window in a tab page
+/// Gets the current window in a tabpage
///
-/// @param tabpage The tab page handle
-/// @param[out] err Details of an error that may have occurred
-/// @return The Window handle
+/// @param tabpage Tabpage handle
+/// @param[out] err Error details, if any
+/// @return Window handle
Window nvim_tabpage_get_win(Tabpage tabpage, Error *err)
{
Window rv = 0;
@@ -159,11 +159,11 @@ Window nvim_tabpage_get_win(Tabpage tabpage, Error *err)
}
}
-/// Gets the tab page number
+/// Gets the tabpage number
///
-/// @param tabpage The tabpage handle
-/// @param[out] err Details of an error that may have occurred
-/// @return The tabpage number
+/// @param tabpage Tabpage handle
+/// @param[out] err Error details, if any
+/// @return Tabpage number
Integer nvim_tabpage_get_number(Tabpage tabpage, Error *err)
{
Integer rv = 0;
@@ -176,10 +176,10 @@ Integer nvim_tabpage_get_number(Tabpage tabpage, Error *err)
return tabpage_index(tab);
}
-/// Checks if a tab page is valid
+/// Checks if a tabpage is valid
///
-/// @param tabpage The tab page handle
-/// @return true if the tab page is valid, false otherwise
+/// @param tabpage Tabpage handle
+/// @return true if the tabpage is valid, false otherwise
Boolean nvim_tabpage_is_valid(Tabpage tabpage)
{
Error stub = ERROR_INIT;
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 9f3a84c88b..15ec52ebab 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -33,24 +33,26 @@
# include "api/vim.c.generated.h"
#endif
-/// Executes an ex-mode command str
+/// Executes an ex-command.
+/// On VimL error: Returns the VimL error and updates v:errmsg.
///
-/// @param str The command str
-/// @param[out] err Details of an error that may have occurred
-void nvim_command(String str, Error *err)
+/// @param command Ex-command string
+/// @param[out] err Error details (including actual VimL error), if any
+void nvim_command(String command, Error *err)
{
// Run the command
try_start();
- do_cmdline_cmd(str.data);
+ do_cmdline_cmd(command.data);
update_screen(VALID);
try_end(err);
}
-/// Passes input keys to Neovim
+/// Passes input keys to Nvim.
+/// On VimL error: Does not fail, but updates v:errmsg.
///
-/// @param keys to be typed
-/// @param mode specifies the mapping options
-/// @param escape_csi the string needs escaping for K_SPECIAL/CSI bytes
+/// @param keys to be typed
+/// @param mode mapping options
+/// @param escape_csi If true, escape K_SPECIAL/CSI bytes in `keys`
/// @see feedkeys()
/// @see vim_strsave_escape_csi
void nvim_feedkeys(String keys, String mode, Boolean escape_csi)
@@ -102,13 +104,15 @@ void nvim_feedkeys(String keys, String mode, Boolean escape_csi)
}
}
-/// Passes input keys to Neovim. Unlike `nvim_feedkeys`, this will use a
-/// lower-level input buffer and the call is not deferred.
-/// This is the most reliable way to emulate real user input.
+/// Passes keys to Nvim as raw user-input.
+/// On VimL error: Does not fail, but updates v:errmsg.
+///
+/// Unlike `nvim_feedkeys`, this uses a lower-level input buffer and the call
+/// is not deferred. This is the most reliable way to emulate real user input.
///
/// @param keys to be typed
-/// @return The number of bytes actually written, which can be lower than
-/// requested if the buffer becomes full.
+/// @return Number of bytes actually written (can be fewer than
+/// requested if the buffer becomes full).
Integer nvim_input(String keys)
FUNC_API_ASYNC
{
@@ -152,19 +156,19 @@ String nvim_command_output(String str, Error *err)
return cstr_to_string((char *)get_vim_var_str(VV_COMMAND_OUTPUT));
}
-/// Evaluates the expression str using the Vim internal expression
-/// evaluator (see |expression|).
-/// Dictionaries and lists are recursively expanded.
+/// Evaluates a VimL expression (:help expression).
+/// Dictionaries and Lists are recursively expanded.
+/// On VimL error: Returns a generic error; v:errmsg is not updated.
///
-/// @param str The expression str
-/// @param[out] err Details of an error that may have occurred
-/// @return The expanded object
-Object nvim_eval(String str, Error *err)
+/// @param expr VimL expression string
+/// @param[out] err Error details, if any
+/// @return Evaluation result or expanded object
+Object nvim_eval(String expr, Error *err)
{
Object rv = OBJECT_INIT;
// Evaluate the expression
try_start();
- typval_T *expr_result = eval_expr((char_u *) str.data, NULL);
+ typval_T *expr_result = eval_expr((char_u *)expr.data, NULL);
if (!expr_result) {
api_set_error(err, Exception, _("Failed to evaluate expression"));
@@ -180,11 +184,12 @@ Object nvim_eval(String str, Error *err)
return rv;
}
-/// Call the given function with the given arguments stored in an array.
+/// Calls a VimL function with the given arguments.
+/// On VimL error: Returns a generic error; v:errmsg is not updated.
///
-/// @param fname Function to call
-/// @param args Functions arguments packed in an Array
-/// @param[out] err Details of an error that may have occurred
+/// @param fname Function to call
+/// @param args Function arguments packed in an Array
+/// @param[out] err Error details, if any
/// @return Result of the function call
Object nvim_call_function(String fname, Array args, Error *err)
{
@@ -229,12 +234,12 @@ free_vim_args:
return rv;
}
-/// Calculates the number of display cells `str` occupies, tab is counted as
-/// one cell.
+/// Calculates the number of display cells occupied by `text`.
+/// <Tab> counts as one cell.
///
-/// @param str Some text
-/// @param[out] err Details of an error that may have occurred
-/// @return The number of cells
+/// @param text Some text
+/// @param[out] err Error details, if any
+/// @return Number of cells
Integer nvim_strwidth(String str, Error *err)
{
if (str.size > INT_MAX) {
@@ -245,9 +250,9 @@ Integer nvim_strwidth(String str, Error *err)
return (Integer) mb_string2cells((char_u *) str.data);
}
-/// Gets a list of paths contained in 'runtimepath'
+/// Gets the paths contained in 'runtimepath'.
///
-/// @return The list of paths
+/// @return List of paths
ArrayOf(String) nvim_list_runtime_paths(void)
{
Array rv = ARRAY_DICT_INIT;
@@ -285,10 +290,10 @@ ArrayOf(String) nvim_list_runtime_paths(void)
return rv;
}
-/// Changes Vim working directory
+/// Changes the global working directory.
///
-/// @param dir The new working directory
-/// @param[out] err Details of an error that may have occurred
+/// @param dir Directory path
+/// @param[out] err Error details, if any
void nvim_set_current_dir(String dir, Error *err)
{
if (dir.size >= MAXPATHL) {
@@ -315,8 +320,8 @@ void nvim_set_current_dir(String dir, Error *err)
/// Gets the current line
///
-/// @param[out] err Details of an error that may have occurred
-/// @return The current line string
+/// @param[out] err Error details, if any
+/// @return Current line string
String nvim_get_current_line(Error *err)
{
return buffer_get_line(curbuf->handle, curwin->w_cursor.lnum - 1, err);
@@ -324,8 +329,8 @@ String nvim_get_current_line(Error *err)
/// Sets the current line
///
-/// @param line The line contents
-/// @param[out] err Details of an error that may have occurred
+/// @param line Line contents
+/// @param[out] err Error details, if any
void nvim_set_current_line(String line, Error *err)
{
buffer_set_line(curbuf->handle, curwin->w_cursor.lnum - 1, line, err);
@@ -333,36 +338,36 @@ void nvim_set_current_line(String line, Error *err)
/// Deletes the current line
///
-/// @param[out] err Details of an error that may have occurred
+/// @param[out] err Error details, if any
void nvim_del_current_line(Error *err)
{
buffer_del_line(curbuf->handle, curwin->w_cursor.lnum - 1, err);
}
-/// Gets a global variable
+/// Gets a global (g:) variable
///
-/// @param name The variable name
-/// @param[out] err Details of an error that may have occurred
-/// @return The variable value
+/// @param name Variable name
+/// @param[out] err Error details, if any
+/// @return Variable value
Object nvim_get_var(String name, Error *err)
{
return dict_get_value(&globvardict, name, err);
}
-/// Sets a global variable
+/// Sets a global (g:) variable
///
-/// @param name The variable name
-/// @param value The variable value
-/// @param[out] err Details of an error that may have occurred
+/// @param name Variable name
+/// @param value Variable value
+/// @param[out] err Error details, if any
void nvim_set_var(String name, Object value, Error *err)
{
dict_set_value(&globvardict, name, value, false, false, err);
}
-/// Removes a global variable
+/// Removes a global (g:) variable
///
-/// @param name The variable name
-/// @param[out] err Details of an error that may have occurred
+/// @param name Variable name
+/// @param[out] err Error details, if any
void nvim_del_var(String name, Error *err)
{
dict_set_value(&globvardict, name, NIL, true, false, err);
@@ -372,10 +377,10 @@ void nvim_del_var(String name, Error *err)
///
/// @deprecated
///
-/// @param name The variable name
-/// @param value The variable value
-/// @param[out] err Details of an error that may have occurred
-/// @return The old value or nil if there was no previous value.
+/// @param name Variable name
+/// @param value Variable value
+/// @param[out] err Error details, if any
+/// @return Old value or nil if there was no previous value.
///
/// @warning It may return nil if there was no previous value
/// or if previous value was `v:null`.
@@ -388,19 +393,19 @@ Object vim_set_var(String name, Object value, Error *err)
///
/// @deprecated
///
-/// @param name The variable name
-/// @param[out] err Details of an error that may have occurred
-/// @return The old value
+/// @param name Variable name
+/// @param[out] err Error details, if any
+/// @return Old value
Object vim_del_var(String name, Error *err)
{
return dict_set_value(&globvardict, name, NIL, true, true, err);
}
-/// Gets a vim variable
+/// Gets a v: variable
///
-/// @param name The variable name
-/// @param[out] err Details of an error that may have occurred
-/// @return The variable value
+/// @param name Variable name
+/// @param[out] err Error details, if any
+/// @return Variable value
Object nvim_get_vvar(String name, Error *err)
{
return dict_get_value(&vimvardict, name, err);
@@ -408,9 +413,9 @@ Object nvim_get_vvar(String name, Error *err)
/// Gets an option value string
///
-/// @param name The option name
-/// @param[out] err Details of an error that may have occurred
-/// @return The option value
+/// @param name Option name
+/// @param[out] err Error details, if any
+/// @return Option value
Object nvim_get_option(String name, Error *err)
{
return get_option_from(NULL, SREQ_GLOBAL, name, err);
@@ -418,9 +423,9 @@ Object nvim_get_option(String name, Error *err)
/// Sets an option value
///
-/// @param name The option name
-/// @param value The new option value
-/// @param[out] err Details of an error that may have occurred
+/// @param name Option name
+/// @param value New option value
+/// @param[out] err Error details, if any
void nvim_set_option(String name, Object value, Error *err)
{
set_option_to(NULL, SREQ_GLOBAL, name, value, err);
@@ -428,7 +433,7 @@ void nvim_set_option(String name, Object value, Error *err)
/// Writes a message to vim output buffer
///
-/// @param str The message
+/// @param str Message
void nvim_out_write(String str)
{
write_msg(str, false);
@@ -436,16 +441,17 @@ void nvim_out_write(String str)
/// Writes a message to vim error buffer
///
-/// @param str The message
+/// @param str Message
void nvim_err_write(String str)
{
write_msg(str, true);
}
-/// Higher level error reporting function that ensures all str contents
-/// are written by sending a trailing linefeed to `nvim_err_write`
+/// Writes a message to vim error buffer. Appends a linefeed to ensure all
+/// contents are written.
///
-/// @param str The message
+/// @param str Message
+/// @see nvim_err_write()
void nvim_err_writeln(String str)
{
nvim_err_write(str);
@@ -454,7 +460,7 @@ void nvim_err_writeln(String str)
/// Gets the current list of buffer handles
///
-/// @return The number of buffers
+/// @return List of buffer handles
ArrayOf(Buffer) nvim_list_bufs(void)
{
Array rv = ARRAY_DICT_INIT;
@@ -475,7 +481,7 @@ ArrayOf(Buffer) nvim_list_bufs(void)
/// Gets the current buffer
///
-/// @reqturn The buffer handle
+/// @return Buffer handle
Buffer nvim_get_current_buf(void)
{
return curbuf->handle;
@@ -483,8 +489,8 @@ Buffer nvim_get_current_buf(void)
/// Sets the current buffer
///
-/// @param id The buffer handle
-/// @param[out] err Details of an error that may have occurred
+/// @param id Buffer handle
+/// @param[out] err Error details, if any
void nvim_set_current_buf(Buffer buffer, Error *err)
{
buf_T *buf = find_buffer_by_handle(buffer, err);
@@ -505,7 +511,7 @@ void nvim_set_current_buf(Buffer buffer, Error *err)
/// Gets the current list of window handles
///
-/// @return The number of windows
+/// @return List of window handles
ArrayOf(Window) nvim_list_wins(void)
{
Array rv = ARRAY_DICT_INIT;
@@ -526,7 +532,7 @@ ArrayOf(Window) nvim_list_wins(void)
/// Gets the current window
///
-/// @return The window handle
+/// @return Window handle
Window nvim_get_current_win(void)
{
return curwin->handle;
@@ -534,7 +540,7 @@ Window nvim_get_current_win(void)
/// Sets the current window
///
-/// @param handle The window handle
+/// @param handle Window handle
void nvim_set_current_win(Window window, Error *err)
{
win_T *win = find_window_by_handle(window, err);
@@ -555,7 +561,7 @@ void nvim_set_current_win(Window window, Error *err)
/// Gets the current list of tabpage handles
///
-/// @return The number of tab pages
+/// @return List of tabpage handles
ArrayOf(Tabpage) nvim_list_tabpages(void)
{
Array rv = ARRAY_DICT_INIT;
@@ -574,18 +580,18 @@ ArrayOf(Tabpage) nvim_list_tabpages(void)
return rv;
}
-/// Gets the current tab page
+/// Gets the current tabpage
///
-/// @return The tab page handle
+/// @return Tabpage handle
Tabpage nvim_get_current_tabpage(void)
{
return curtab->handle;
}
-/// Sets the current tab page
+/// Sets the current tabpage
///
-/// @param handle The tab page handle
-/// @param[out] err Details of an error that may have occurred
+/// @param handle Tabpage handle
+/// @param[out] err Error details, if any
void nvim_set_current_tabpage(Tabpage tabpage, Error *err)
{
tabpage_T *tp = find_tab_by_handle(tabpage, err);
@@ -606,8 +612,8 @@ void nvim_set_current_tabpage(Tabpage tabpage, Error *err)
/// Subscribes to event broadcasts
///
-/// @param channel_id The channel id (passed automatically by the dispatcher)
-/// @param event The event type string
+/// @param channel_id Channel id (passed automatically by the dispatcher)
+/// @param event Event type string
void nvim_subscribe(uint64_t channel_id, String event)
FUNC_API_NOEVAL
{
@@ -620,8 +626,8 @@ void nvim_subscribe(uint64_t channel_id, String event)
/// Unsubscribes to event broadcasts
///
-/// @param channel_id The channel id (passed automatically by the dispatcher)
-/// @param event The event type string
+/// @param channel_id Channel id (passed automatically by the dispatcher)
+/// @param event Event type string
void nvim_unsubscribe(uint64_t channel_id, String event)
FUNC_API_NOEVAL
{
@@ -756,9 +762,8 @@ validation_error:
/// and flushed after each newline. Incomplete lines are kept for writing
/// later.
///
-/// @param message The message to write
-/// @param to_err true if it should be treated as an error message (use
-/// `emsg` instead of `msg` to print each line)
+/// @param message Message to write
+/// @param to_err true: message is an error (uses `emsg` instead of `msg`)
static void write_msg(String message, bool to_err)
{
static size_t out_pos = 0, err_pos = 0;
diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c
index 382f65e7d9..ef881fa0eb 100644
--- a/src/nvim/api/window.c
+++ b/src/nvim/api/window.c
@@ -15,9 +15,9 @@
/// Gets the current buffer in a window
///
-/// @param window The window handle
-/// @param[out] err Details of an error that may have occurred
-/// @return The buffer handle
+/// @param window Window handle
+/// @param[out] err Error details, if any
+/// @return Buffer handle
Buffer nvim_win_get_buf(Window window, Error *err)
{
win_T *win = find_window_by_handle(window, err);
@@ -31,9 +31,9 @@ Buffer nvim_win_get_buf(Window window, Error *err)
/// Gets the cursor position in the window
///
-/// @param window The window handle
-/// @param[out] err Details of an error that may have occurred
-/// @return the (row, col) tuple
+/// @param window Window handle
+/// @param[out] err Error details, if any
+/// @return (row, col) tuple
ArrayOf(Integer, 2) nvim_win_get_cursor(Window window, Error *err)
{
Array rv = ARRAY_DICT_INIT;
@@ -49,9 +49,9 @@ ArrayOf(Integer, 2) nvim_win_get_cursor(Window window, Error *err)
/// Sets the cursor position in the window
///
-/// @param window The window handle
-/// @param pos the (row, col) tuple representing the new position
-/// @param[out] err Details of an error that may have occurred
+/// @param window Window handle
+/// @param pos (row, col) tuple representing the new position
+/// @param[out] err Error details, if any
void nvim_win_set_cursor(Window window, ArrayOf(Integer, 2) pos, Error *err)
{
win_T *win = find_window_by_handle(window, err);
@@ -95,9 +95,9 @@ void nvim_win_set_cursor(Window window, ArrayOf(Integer, 2) pos, Error *err)
/// Gets the window height
///
-/// @param window The window handle
-/// @param[out] err Details of an error that may have occurred
-/// @return the height in rows
+/// @param window Window handle
+/// @param[out] err Error details, if any
+/// @return Height as a count of rows
Integer nvim_win_get_height(Window window, Error *err)
{
win_T *win = find_window_by_handle(window, err);
@@ -112,9 +112,9 @@ Integer nvim_win_get_height(Window window, Error *err)
/// Sets the window height. This will only succeed if the screen is split
/// horizontally.
///
-/// @param window The window handle
-/// @param height the new height in rows
-/// @param[out] err Details of an error that may have occurred
+/// @param window Window handle
+/// @param height Height as a count of rows
+/// @param[out] err Error details, if any
void nvim_win_set_height(Window window, Integer height, Error *err)
{
win_T *win = find_window_by_handle(window, err);
@@ -138,9 +138,9 @@ void nvim_win_set_height(Window window, Integer height, Error *err)
/// Gets the window width
///
-/// @param window The window handle
-/// @param[out] err Details of an error that may have occurred
-/// @return the width in columns
+/// @param window Window handle
+/// @param[out] err Error details, if any
+/// @return Width as a count of columns
Integer nvim_win_get_width(Window window, Error *err)
{
win_T *win = find_window_by_handle(window, err);
@@ -155,9 +155,9 @@ Integer nvim_win_get_width(Window window, Error *err)
/// Sets the window width. This will only succeed if the screen is split
/// vertically.
///
-/// @param window The window handle
-/// @param width the new width in columns
-/// @param[out] err Details of an error that may have occurred
+/// @param window Window handle
+/// @param width Width as a count of columns
+/// @param[out] err Error details, if any
void nvim_win_set_width(Window window, Integer width, Error *err)
{
win_T *win = find_window_by_handle(window, err);
@@ -181,10 +181,10 @@ void nvim_win_set_width(Window window, Integer width, Error *err)
/// Gets a window-scoped (w:) variable
///
-/// @param window The window handle
-/// @param name The variable name
-/// @param[out] err Details of an error that may have occurred
-/// @return The variable value
+/// @param window Window handle
+/// @param name Variable name
+/// @param[out] err Error details, if any
+/// @return Variable value
Object nvim_win_get_var(Window window, String name, Error *err)
{
win_T *win = find_window_by_handle(window, err);
@@ -198,10 +198,10 @@ Object nvim_win_get_var(Window window, String name, Error *err)
/// Sets a window-scoped (w:) variable
///
-/// @param window The window handle
-/// @param name The variable name
-/// @param value The variable value
-/// @param[out] err Details of an error that may have occurred
+/// @param window Window handle
+/// @param name Variable name
+/// @param value Variable value
+/// @param[out] err Error details, if any
void nvim_win_set_var(Window window, String name, Object value, Error *err)
{
win_T *win = find_window_by_handle(window, err);
@@ -215,9 +215,9 @@ void nvim_win_set_var(Window window, String name, Object value, Error *err)
/// Removes a window-scoped (w:) variable
///
-/// @param window The window handle
-/// @param name The variable name
-/// @param[out] err Details of an error that may have occurred
+/// @param window Window handle
+/// @param name Variable name
+/// @param[out] err Error details, if any
void nvim_win_del_var(Window window, String name, Error *err)
{
win_T *win = find_window_by_handle(window, err);
@@ -233,11 +233,11 @@ void nvim_win_del_var(Window window, String name, Error *err)
///
/// @deprecated
///
-/// @param window The window handle
-/// @param name The variable name
-/// @param value The variable value
-/// @param[out] err Details of an error that may have occurred
-/// @return The old value or nil if there was no previous value.
+/// @param window Window handle
+/// @param name Variable name
+/// @param value Variable value
+/// @param[out] err Error details, if any
+/// @return Old value or nil if there was no previous value.
///
/// @warning It may return nil if there was no previous value
/// or if previous value was `v:null`.
@@ -256,10 +256,10 @@ Object window_set_var(Window window, String name, Object value, Error *err)
///
/// @deprecated
///
-/// @param window The window handle
-/// @param name The variable name
-/// @param[out] err Details of an error that may have occurred
-/// @return The old value
+/// @param window Window handle
+/// @param name variable name
+/// @param[out] err Error details, if any
+/// @return Old value
Object window_del_var(Window window, String name, Error *err)
{
win_T *win = find_window_by_handle(window, err);
@@ -273,10 +273,10 @@ Object window_del_var(Window window, String name, Error *err)
/// Gets a window option value
///
-/// @param window The window handle
-/// @param name The option name
-/// @param[out] err Details of an error that may have occurred
-/// @return The option value
+/// @param window Window handle
+/// @param name Option name
+/// @param[out] err Error details, if any
+/// @return Option value
Object nvim_win_get_option(Window window, String name, Error *err)
{
win_T *win = find_window_by_handle(window, err);
@@ -291,10 +291,10 @@ Object nvim_win_get_option(Window window, String name, Error *err)
/// Sets a window option value. Passing 'nil' as value deletes the option(only
/// works if there's a global fallback)
///
-/// @param window The window handle
-/// @param name The option name
-/// @param value The option value
-/// @param[out] err Details of an error that may have occurred
+/// @param window Window handle
+/// @param name Option name
+/// @param value Option value
+/// @param[out] err Error details, if any
void nvim_win_set_option(Window window, String name, Object value, Error *err)
{
win_T *win = find_window_by_handle(window, err);
@@ -308,9 +308,9 @@ void nvim_win_set_option(Window window, String name, Object value, Error *err)
/// Gets the window position in display cells. First position is zero.
///
-/// @param window The window handle
-/// @param[out] err Details of an error that may have occurred
-/// @return The (row, col) tuple with the window position
+/// @param window Window handle
+/// @param[out] err Error details, if any
+/// @return (row, col) tuple with the window position
ArrayOf(Integer, 2) nvim_win_get_position(Window window, Error *err)
{
Array rv = ARRAY_DICT_INIT;
@@ -324,11 +324,11 @@ ArrayOf(Integer, 2) nvim_win_get_position(Window window, Error *err)
return rv;
}
-/// Gets the window tab page
+/// Gets the window tabpage
///
-/// @param window The window handle
-/// @param[out] err Details of an error that may have occurred
-/// @return The tab page that contains the window
+/// @param window Window handle
+/// @param[out] err Error details, if any
+/// @return Tabpage that contains the window
Tabpage nvim_win_get_tabpage(Window window, Error *err)
{
Tabpage rv = 0;
@@ -343,9 +343,9 @@ Tabpage nvim_win_get_tabpage(Window window, Error *err)
/// Gets the window number
///
-/// @param window The window handle
-/// @param[out] err Details of an error that may have occurred
-/// @return The window number
+/// @param window Window handle
+/// @param[out] err Error details, if any
+/// @return Window number
Integer nvim_win_get_number(Window window, Error *err)
{
Integer rv = 0;
@@ -363,7 +363,7 @@ Integer nvim_win_get_number(Window window, Error *err)
/// Checks if a window is valid
///
-/// @param window The window handle
+/// @param window Window handle
/// @return true if the window is valid, false otherwise
Boolean nvim_win_is_valid(Window window)
{
generated by cgit (git 2.34.1) at 2025-05-28 08:52:23 +0000