doc [ci skip]

closes #9719

1 files changed, 132 insertions, 139 deletions

diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 25f7a2a496..de323c7658 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -214,8 +214,8 @@ Integer nvim_input(String keys)
 
 /// Send mouse event from GUI.
 ///
-/// The call is non-blocking. It doesn't wait on any resulting action, but
-/// queues the event to be processed soon by the event loop.
+/// Non-blocking: does not wait on any result, but queues the event to be
+/// processed soon by the event loop.
 ///
 /// @note Currently this doesn't support "scripting" multiple mouse events
 ///       by calling it multiple times in a loop: the intermediate mouse
@@ -233,6 +233,7 @@ Integer nvim_input(String keys)
 /// @param grid Grid number if the client uses |ui-multigrid|, else 0.
 /// @param row Mouse row-position (zero-based, like redraw events)
 /// @param col Mouse column-position (zero-based, like redraw events)
+/// @param[out] err Error details, if any
 void nvim_input_mouse(String button, String action, String modifier,
                       Integer grid, Integer row, Integer col, Error *err)
   FUNC_API_SINCE(6) FUNC_API_ASYNC
@@ -756,9 +757,9 @@ void nvim_del_var(String name, Error *err)
 
 /// @deprecated
 /// @see nvim_set_var
-/// @return Old value or nil if there was no previous value.
 /// @warning May return nil if there was no previous value
 ///          OR if previous value was `v:null`.
+/// @return Old value or nil if there was no previous value.
 Object vim_set_var(String name, Object value, Error *err)
 {
   return dict_set_var(&globvardict, name, value, false, true, err);
@@ -806,6 +807,7 @@ Object nvim_get_option(String name, Error *err)
 
 /// Sets an option value.
 ///
+/// @param channel_id
 /// @param name     Option name
 /// @param value    New option value
 /// @param[out] err Error details, if any
@@ -938,6 +940,7 @@ Window nvim_get_current_win(void)
 /// Sets the current window.
 ///
 /// @param window Window handle
+/// @param[out] err Error details, if any
 void nvim_set_current_win(Window window, Error *err)
   FUNC_API_SINCE(1)
 {
@@ -959,7 +962,7 @@ void nvim_set_current_win(Window window, Error *err)
 
 /// Creates a new, empty, unnamed buffer.
 ///
-/// @param listed Controls 'buflisted'
+/// @param listed Sets 'buflisted'
 /// @param scratch Creates a "throwaway" |scratch-buffer| for temporary work
 ///                (always 'nomodified')
 /// @param[out] err Error details, if any
@@ -1002,37 +1005,6 @@ Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err)
 ///
 /// Exactly one of `external` and `relative` must be specified.
 ///
-/// @param buffer handle of buffer to be displayed in the window
-/// @param enter  whether the window should be entered (made the current window)
-/// @param config Dictionary for the window configuration accepts these keys:
-///
-///     `relative`: If set, the window becomes a floating window. The window
-///         will be placed with row,col coordinates relative to one of the
-///         following:
-///        "editor" the global editor grid
-///        "win"    a window. Use `win` to specify a window id,
-///                 or the current window will be used by default.
-///        "cursor" the cursor position in current window.
-///     `win`: When using relative='win', window id of the window where the
-///         position is defined.
-///     `anchor`: The corner of the float that the row,col position defines:
-///        "NW" north-west (default)
-///        "NE" north-east
-///        "SW" south-west
-///        "SE" south-east
-///     `height`: window height (in character cells). Minimum of 1.
-///     `width`: window width (in character cells). Minimum of 2.
-///     `row`: row position. Screen cell height are used as unit. Can be
-///         floating point.
-///     `col`: column position. Screen cell width is used as unit. Can be
-///         floating point.
-///     `focusable`: Whether window can be focused by wincmds and
-///         mouse events. Defaults to true. Even if set to false, the window
-///         can still be entered using |nvim_set_current_win()| API call.
-///     `external`: GUI should display the window as an external
-///         top-level window. Currently accepts no other positioning
-///         configuration together with this.
-///
 /// With editor positioning row=0, col=0 refers to the top-left corner of the
 /// screen-grid and row=Lines-1, Columns-1 refers to the bottom-right corner.
 /// Floating point values are allowed, but the builtin implementation (used by
@@ -1045,8 +1017,38 @@ Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err)
 /// could let floats hover outside of the main window like a tooltip, but
 /// this should not be used to specify arbitrary WM screen positions.
 ///
+/// @param buffer handle of buffer to be displayed in the window
+/// @param enter  whether the window should be entered (made the current window)
+/// @param config Dictionary for the window configuration accepts these keys:
+///   - `relative`: If set, the window becomes a floating window. The window
+///       will be placed with row,col coordinates relative to one of the
+///       following:
+///      - "editor" the global editor grid
+///      - "win"    a window. Use `win` to specify a window id,
+///                 or the current window will be used by default.
+///      "cursor" the cursor position in current window.
+///   - `win`: When using relative='win', window id of the window where the
+///       position is defined.
+///   - `anchor`: The corner of the float that the row,col position defines:
+///      - "NW" north-west (default)
+///      - "NE" north-east
+///      - "SW" south-west
+///      - "SE" south-east
+///   - `height`: window height (in character cells). Minimum of 1.
+///   - `width`: window width (in character cells). Minimum of 2.
+///   - `row`: row position. Screen cell height are used as unit. Can be
+///       floating point.
+///   - `col`: column position. Screen cell width is used as unit. Can be
+///       floating point.
+///   - `focusable`: Whether window can be focused by wincmds and
+///       mouse events. Defaults to true. Even if set to false, the window
+///       can still be entered using |nvim_set_current_win()| API call.
+///   - `external`: GUI should display the window as an external
+///       top-level window. Currently accepts no other positioning
+///       configuration together with this.
 /// @param[out] err Error details, if any
-/// @return the window handle or 0 when error
+///
+/// @return Window handle, or 0 on error
 Window nvim_open_win(Buffer buffer, Boolean enter, Dictionary config,
                      Error *err)
   FUNC_API_SINCE(6)
@@ -1273,47 +1275,48 @@ Array nvim_get_api_info(uint64_t channel_id)
   return rv;
 }
 
-/// Identify the client for nvim. Can be called more than once, but subsequent
-/// calls will remove earlier info, which should be resent if it is still
-/// valid. (This could happen if a library first identifies the channel, and a
+/// Identifies the client. Can be called more than once; subsequent calls
+/// remove earlier info, which should be included by the caller if it is
+/// still valid. (E.g. if a library first identifies the channel, then a
 /// plugin using that library later overrides that info)
 ///
-/// @param name short name for the connected client
-/// @param version  Dictionary describing the version, with the following
-///                 possible keys (all optional)
+/// @param channel_id
+/// @param name Short name for the connected client
+/// @param version  Dictionary describing the version, with these
+///                 (optional) keys:
 ///     - "major" major version (defaults to 0 if not set, for no release yet)
 ///     - "minor" minor version
 ///     - "patch" patch number
 ///     - "prerelease" string describing a prerelease, like "dev" or "beta1"
 ///     - "commit" hash or similar identifier of commit
-/// @param type Must be one of the following values. A client library should
-///             use "remote" if the library user hasn't specified other value.
-///     - "remote" remote client that connected to nvim.
+/// @param type Must be one of the following values. Client libraries should
+///             default to "remote" unless overridden by the user.
+///     - "remote" remote client connected to Nvim.
 ///     - "ui" gui frontend
-///     - "embedder" application using nvim as a component, for instance
-///                  IDE/editor implementing a vim mode.
+///     - "embedder" application using Nvim as a component (for example,
+///                  IDE/editor implementing a vim mode).
 ///     - "host" plugin host, typically started by nvim
 ///     - "plugin" single plugin, started by nvim
 /// @param methods Builtin methods in the client. For a host, this does not
 ///                include plugin methods which will be discovered later.
 ///                The key should be the method name, the values are dicts with
-///                the following (optional) keys:
+///                these (optional) keys (more keys may be added in future
+///                versions of Nvim, thus unknown keys are ignored. Clients
+///                must only use keys defined in this or later versions of
+///                Nvim):
 ///     - "async"  if true, send as a notification. If false or unspecified,
 ///                use a blocking request
 ///     - "nargs" Number of arguments. Could be a single integer or an array
-///                two integers, minimum and maximum inclusive.
-///     Further keys might be added in later versions of nvim and unknown keys
-///     are thus ignored. Clients must only use keys defined in this or later
-///     versions of nvim!
-///
-/// @param attributes Informal attributes describing the client. Clients might
-///                   define their own keys, but the following are suggested:
-///     - "website" Website of client (for instance github repository)
-///     - "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 format is preferred.
+///                of two integers, minimum and maximum inclusive.
 ///
+/// @param attributes Arbitrary string:string map of informal client properties.
+///     Suggested keys:
+///     - "website": Client homepage URL (e.g. GitHub repository)
+///     - "license": License description ("Apache 2", "GPLv3", "MIT", …)
+///     - "logo":    URI or path to image, preferably small logo or icon.
+///                  .png or .svg format is preferred.
+///
+/// @param[out] err Error details, if any
 void nvim_set_client_info(uint64_t channel_id, String name,
                           Dictionary version, String type,
                           Dictionary methods, Dictionary attributes,
@@ -1345,15 +1348,14 @@ void nvim_set_client_info(uint64_t channel_id, String name,
 
 /// Get information about a channel.
 ///
-/// @returns a Dictionary, describing a channel with the
-/// following keys:
-///     - "stream"  the stream underlying the channel
+/// @returns Dictionary describing a channel, with these keys:
+///    - "stream"  the stream underlying the channel
 ///         - "stdio"      stdin and stdout of this Nvim instance
 ///         - "stderr"     stderr of this Nvim instance
 ///         - "socket"     TCP/IP socket or named pipe
 ///         - "job"        job with communication over its stdio
 ///    -  "mode"    how data received on the channel is interpreted
-///         - "bytes"      send and recieve raw bytes
+///         - "bytes"      send and receive raw bytes
 ///         - "terminal"   a |terminal| instance interprets ASCII sequences
 ///         - "rpc"        |RPC| communication on the channel is active
 ///    -  "pty"     Name of pseudoterminal, if one is used (optional).
@@ -1394,13 +1396,13 @@ Array nvim_list_chans(void)
 ///    processing which have such side-effects, e.g. |:sleep| may wake timers).
 /// 2. To minimize RPC overhead (roundtrips) of a sequence of many requests.
 ///
+/// @param channel_id
 /// @param calls an array of calls, where each call is described by an array
-/// with two elements: the request name, and an array of arguments.
-/// @param[out] err Details of a validation error of the nvim_multi_request call
-/// itself, i.e. malformed `calls` parameter. Errors from called methods will
-/// be indicated in the return value, see below.
+///              with two elements: the request name, and an array of arguments.
+/// @param[out] err Validation error details (malformed `calls` parameter),
+///             if any. Errors from batched calls are given in the return value.
 ///
-/// @return an array with two elements. The first is an array of return
+/// @return Array of two elements. The first is an array of return
 /// values. The second is NIL if all calls succeeded. If a call resulted in
 /// an error, it is a three-element array with the zero-based index of the call
 /// which resulted in an error, the error type and the error message. If an
@@ -1491,9 +1493,8 @@ typedef kvec_withinit_t(ExprASTConvStackItem, 16) ExprASTConvStack;
 
 /// Parse a VimL expression.
 ///
-/// @param[in]  expr  Expression to parse. Is always treated as a single line.
-/// @param[in]  flags  Flags:
-///
+/// @param[in]  expr  Expression to parse. Always treated as a single line.
+/// @param[in]  flags Flags:
 ///                    - "m" if multiple expressions in a row are allowed (only
 ///                      the first one will be parsed),
 ///                    - "E" if EOC tokens are not allowed (determines whether
@@ -1501,7 +1502,6 @@ typedef kvec_withinit_t(ExprASTConvStackItem, 16) ExprASTConvStack;
 ///                      operator/space, though also yielding an error).
 ///                    - "l" when needing to start parsing with lvalues for
 ///                      ":let" or ":for".
-///
 ///                    Common flag sets:
 ///                    - "m" to parse like for ":echo".
 ///                    - "E" to parse like for "<C-r>=".
@@ -1514,63 +1514,57 @@ typedef kvec_withinit_t(ExprASTConvStackItem, 16) ExprASTConvStack;
 ///                        starting column and ending column (latter exclusive:
 ///                        one should highlight region [start_col, end_col)).
 ///
-/// @return AST: top-level dictionary with these keys:
-///
-///         "error": Dictionary with error, present only if parser saw some
-///                  error. Contains the following keys:
-///
-///           "message": String, error message in printf format, translated.
-///                      Must contain exactly one "%.*s".
-///           "arg": String, error message argument.
-///
-///         "len": Amount of bytes successfully parsed. With flags equal to ""
-///                that should be equal to the length of expr string.
-///
-///                @note: “Sucessfully parsed” here means “participated in AST
-///                       creation”, not “till the first error”.
-///
-///         "ast": AST, either nil or a dictionary with these keys:
-///
-///           "type": node type, one of the value names from ExprASTNodeType
-///                   stringified without "kExprNode" prefix.
-///           "start": a pair [line, column] describing where node is “started”
-///                    where "line" is always 0 (will not be 0 if you will be
-///                    using nvim_parse_viml() on e.g. ":let", but that is not
-///                    present yet). Both elements are Integers.
-///           "len": “length” of the node. This and "start" are there for
-///                  debugging purposes primary (debugging parser and providing
-///                  debug information).
-///           "children": a list of nodes described in top/"ast". There always
-///                       is zero, one or two children, key will not be present
-///                       if node has no children. Maximum number of children
-///                       may be found in node_maxchildren array.
-///
-///           Local values (present only for certain nodes):
-///
-///           "scope": a single Integer, specifies scope for "Option" and
-///                    "PlainIdentifier" nodes. For "Option" it is one of
-///                    ExprOptScope values, for "PlainIdentifier" it is one of
-///                    ExprVarScope values.
-///           "ident": identifier (without scope, if any), present for "Option",
-///                    "PlainIdentifier", "PlainKey" and "Environment" nodes.
-///           "name": Integer, register name (one character) or -1. Only present
-///                   for "Register" nodes.
-///           "cmp_type": String, comparison type, one of the value names from
-///                       ExprComparisonType, stringified without "kExprCmp"
-///                       prefix. Only present for "Comparison" nodes.
-///           "ccs_strategy": String, case comparison strategy, one of the
-///                           value names from ExprCaseCompareStrategy,
-///                           stringified without "kCCStrategy" prefix. Only
-///                           present for "Comparison" nodes.
-///           "augmentation": String, augmentation type for "Assignment" nodes.
-///                           Is either an empty string, "Add", "Subtract" or
-///                           "Concat" for "=", "+=", "-=" or ".=" respectively.
-///           "invert": Boolean, true if result of comparison needs to be
-///                     inverted. Only present for "Comparison" nodes.
-///           "ivalue": Integer, integer value for "Integer" nodes.
-///           "fvalue": Float, floating-point value for "Float" nodes.
-///           "svalue": String, value for "SingleQuotedString" and
-///                     "DoubleQuotedString" nodes.
+/// @return
+///      - AST: top-level dictionary with these keys:
+///        - "error": Dictionary with error, present only if parser saw some
+///                 error. Contains the following keys:
+///          - "message": String, error message in printf format, translated.
+///                       Must contain exactly one "%.*s".
+///          - "arg": String, error message argument.
+///        - "len": Amount of bytes successfully parsed. With flags equal to ""
+///                 that should be equal to the length of expr string.
+///                 (“Sucessfully parsed” here means “participated in AST
+///                  creation”, not “till the first error”.)
+///        - "ast": AST, either nil or a dictionary with these keys:
+///          - "type": node type, one of the value names from ExprASTNodeType
+///                    stringified without "kExprNode" prefix.
+///          - "start": a pair [line, column] describing where node is "started"
+///                     where "line" is always 0 (will not be 0 if you will be
+///                     using nvim_parse_viml() on e.g. ":let", but that is not
+///                     present yet). Both elements are Integers.
+///          - "len": “length” of the node. This and "start" are there for
+///                   debugging purposes primary (debugging parser and providing
+///                   debug information).
+///          - "children": a list of nodes described in top/"ast". There always
+///                        is zero, one or two children, key will not be present
+///                        if node has no children. Maximum number of children
+///                        may be found in node_maxchildren array.
+///      - Local values (present only for certain nodes):
+///        - "scope": a single Integer, specifies scope for "Option" and
+///                   "PlainIdentifier" nodes. For "Option" it is one of
+///                   ExprOptScope values, for "PlainIdentifier" it is one of
+///                   ExprVarScope values.
+///        - "ident": identifier (without scope, if any), present for "Option",
+///                   "PlainIdentifier", "PlainKey" and "Environment" nodes.
+///        - "name": Integer, register name (one character) or -1. Only present
+///                for "Register" nodes.
+///        - "cmp_type": String, comparison type, one of the value names from
+///                      ExprComparisonType, stringified without "kExprCmp"
+///                      prefix. Only present for "Comparison" nodes.
+///        - "ccs_strategy": String, case comparison strategy, one of the
+///                          value names from ExprCaseCompareStrategy,
+///                          stringified without "kCCStrategy" prefix. Only
+///                          present for "Comparison" nodes.
+///        - "augmentation": String, augmentation type for "Assignment" nodes.
+///                          Is either an empty string, "Add", "Subtract" or
+///                          "Concat" for "=", "+=", "-=" or ".=" respectively.
+///        - "invert": Boolean, true if result of comparison needs to be
+///                    inverted. Only present for "Comparison" nodes.
+///        - "ivalue": Integer, integer value for "Integer" nodes.
+///        - "fvalue": Float, floating-point value for "Float" nodes.
+///        - "svalue": String, value for "SingleQuotedString" and
+///                    "DoubleQuotedString" nodes.
+/// @param[out] err Error details, if any
 Dictionary nvim_parse_expression(String expr, String flags, Boolean highlight,
                                  Error *err)
   FUNC_API_SINCE(4) FUNC_API_ASYNC
@@ -2035,15 +2029,13 @@ Dictionary nvim__stats(void)
 
 /// Gets a list of dictionaries representing attached UIs.
 ///
-/// @return Array of UI dictionaries
-///
-/// Each dictionary has the following keys:
-///     - "height"  requested height of the UI
-///     - "width"   requested width of the UI
-///     - "rgb"     whether the UI uses rgb colors (false implies cterm colors)
-///     - "ext_..." Requested UI extensions, see |ui-options|
-///     - "chan"    Channel id of remote UI (not present for TUI)
-///
+/// @return
+///   Array of UI dictionaries, each with these keys:
+///       - "height"  requested height of the UI
+///       - "width"   requested width of the UI
+///       - "rgb"     whether the UI uses rgb colors (false implies cterm colors)
+///       - "ext_..." Requested UI extensions, see |ui-options|
+///       - "chan"    Channel id of remote UI (not present for TUI)
 Array nvim_list_uis(void)
   FUNC_API_SINCE(4)
 {
@@ -2146,6 +2138,7 @@ Object nvim_get_proc(Integer pid, Error *err)
 /// @param finish Finish the completion and dismiss the popupmenu. Implies
 ///               `insert`.
 /// @param  opts  Optional parameters. Reserved for future use.
+/// @param[out] err Error details, if any
 void nvim_select_popupmenu_item(Integer item, Boolean insert, Boolean finish,
                                 Dictionary opts, Error *err)
   FUNC_API_SINCE(6)