Merge #5523 from justinmk/test-system

test: system(): Avoid indeterminism. Also adjust docs.

1 files changed, 99 insertions, 94 deletions

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;