doc [ci skip]

closes #9719

8 files changed, 180 insertions, 178 deletions

diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 3613a8f8bc..e27c85cd4f 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -49,7 +49,7 @@
 
 /// Gets the buffer line count
 ///
-/// @param buffer   Buffer handle
+/// @param buffer   Buffer handle, or 0 for current buffer
 /// @param[out] err Error details, if any
 /// @return Line count, or 0 for unloaded buffer. |api-buffer|
 Integer nvim_buf_line_count(Buffer buffer, Error *err)
@@ -99,7 +99,8 @@ String buffer_get_line(Buffer buffer, Integer index, Error *err)
 
 /// Activate updates from this buffer to the current channel.
 ///
-/// @param buffer The buffer handle
+/// @param channel_id
+/// @param buffer Buffer handle, or 0 for current buffer
 /// @param send_buffer Set to true if the initial notification should contain
 ///        the whole buffer. If so, the first notification will be a
 ///        `nvim_buf_lines_event`. Otherwise, the first notification will be
@@ -131,7 +132,8 @@ Boolean nvim_buf_attach(uint64_t channel_id,
 //
 /// Deactivate updates from this buffer to the current channel.
 ///
-/// @param buffer The buffer handle
+/// @param channel_id
+/// @param buffer Buffer handle, or 0 for current buffer
 /// @param[out] err Details of an error that may have occurred
 /// @return False when updates couldn't be disabled because the buffer
 ///         isn't loaded; otherwise True.
@@ -221,7 +223,8 @@ 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           Buffer handle
+/// @param channel_id
+/// @param buffer           Buffer handle, or 0 for current buffer
 /// @param start            First line index
 /// @param end              Last line index (exclusive)
 /// @param strict_indexing  Whether out-of-bounds should be an error.
@@ -290,7 +293,7 @@ end:
 ///                   newend = end + int(include_end) + int(end < 0)
 ///                   int(bool) = 1 if bool is true else 0
 ///
-/// @param buffer         Buffer handle
+/// @param buffer         Buffer handle, or 0 for current buffer
 /// @param start          First line index
 /// @param end            Last line index
 /// @param include_start  True if the slice includes the `start` parameter
@@ -324,7 +327,8 @@ 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           Buffer handle
+/// @param channel_id
+/// @param buffer           Buffer handle, or 0 for current buffer
 /// @param start            First line index
 /// @param end              Last line index (exclusive)
 /// @param strict_indexing  Whether out-of-bounds should be an error.
@@ -491,7 +495,7 @@ end:
 /// Unlike |line2byte()|, throws error for out-of-bounds indexing.
 /// Returns -1 for unloaded buffer.
 ///
-/// @param buffer     Buffer handle
+/// @param buffer     Buffer handle, or 0 for current buffer
 /// @param index      Line index
 /// @param[out] err   Error details, if any
 /// @return Integer byte offset, or -1 for unloaded buffer.
@@ -518,7 +522,7 @@ Integer nvim_buf_get_offset(Buffer buffer, Integer index, Error *err)
 
 /// Gets a buffer-scoped (b:) variable.
 ///
-/// @param buffer     Buffer handle
+/// @param buffer     Buffer handle, or 0 for current buffer
 /// @param name       Variable name
 /// @param[out] err   Error details, if any
 /// @return Variable value
@@ -536,7 +540,7 @@ Object nvim_buf_get_var(Buffer buffer, String name, Error *err)
 
 /// Gets a changed tick of a buffer
 ///
-/// @param[in]  buffer  Buffer handle.
+/// @param[in]  buffer  Buffer handle, or 0 for current buffer
 /// @param[out] err     Error details, if any
 ///
 /// @return `b:changedtick` value.
@@ -555,7 +559,7 @@ Integer nvim_buf_get_changedtick(Buffer buffer, Error *err)
 /// Gets a list of buffer-local |mapping| definitions.
 ///
 /// @param  mode       Mode short-name ("n", "i", "v", ...)
-/// @param  buffer     Buffer handle
+/// @param  buffer     Buffer handle, or 0 for current buffer
 /// @param[out]  err   Error details, if any
 /// @returns Array of maparg()-like dictionaries describing mappings.
 ///          The "buffer" key holds the associated buffer handle.
@@ -573,7 +577,7 @@ ArrayOf(Dictionary) nvim_buf_get_keymap(Buffer buffer, String mode, Error *err)
 
 /// Gets a map of buffer-local |user-commands|.
 ///
-/// @param  buffer  Buffer handle.
+/// @param  buffer  Buffer handle, or 0 for current buffer
 /// @param  opts  Optional parameters. Currently not used.
 /// @param[out]  err   Error details, if any.
 ///
@@ -613,7 +617,7 @@ Dictionary nvim_buf_get_commands(Buffer buffer, Dictionary opts, Error *err)
 
 /// Sets a buffer-scoped (b:) variable
 ///
-/// @param buffer     Buffer handle
+/// @param buffer     Buffer handle, or 0 for current buffer
 /// @param name       Variable name
 /// @param value      Variable value
 /// @param[out] err   Error details, if any
@@ -631,7 +635,7 @@ void nvim_buf_set_var(Buffer buffer, String name, Object value, Error *err)
 
 /// Removes a buffer-scoped (b:) variable
 ///
-/// @param buffer     Buffer handle
+/// @param buffer     Buffer handle, or 0 for current buffer
 /// @param name       Variable name
 /// @param[out] err   Error details, if any
 void nvim_buf_del_var(Buffer buffer, String name, Error *err)
@@ -650,7 +654,7 @@ void nvim_buf_del_var(Buffer buffer, String name, Error *err)
 ///
 /// @deprecated
 ///
-/// @param buffer     Buffer handle
+/// @param buffer     Buffer handle, or 0 for current buffer
 /// @param name       Variable name
 /// @param value      Variable value
 /// @param[out] err   Error details, if any
@@ -673,7 +677,7 @@ Object buffer_set_var(Buffer buffer, String name, Object value, Error *err)
 ///
 /// @deprecated
 ///
-/// @param buffer     Buffer handle
+/// @param buffer     Buffer handle, or 0 for current buffer
 /// @param name       Variable name
 /// @param[out] err   Error details, if any
 /// @return Old value
@@ -691,7 +695,7 @@ Object buffer_del_var(Buffer buffer, String name, Error *err)
 
 /// Gets a buffer option value
 ///
-/// @param buffer     Buffer handle
+/// @param buffer     Buffer handle, or 0 for current buffer
 /// @param name       Option name
 /// @param[out] err   Error details, if any
 /// @return Option value
@@ -710,7 +714,8 @@ Object nvim_buf_get_option(Buffer buffer, String name, Error *err)
 /// Sets a buffer option value. Passing 'nil' as value deletes the option (only
 /// works if there's a global fallback)
 ///
-/// @param buffer     Buffer handle
+/// @param channel_id
+/// @param buffer     Buffer handle, or 0 for current buffer
 /// @param name       Option name
 /// @param value      Option value
 /// @param[out] err   Error details, if any
@@ -732,7 +737,7 @@ void nvim_buf_set_option(uint64_t channel_id, Buffer buffer,
 /// @deprecated The buffer number now is equal to the object id,
 ///             so there is no need to use this function.
 ///
-/// @param buffer     Buffer handle
+/// @param buffer     Buffer handle, or 0 for current buffer
 /// @param[out] err   Error details, if any
 /// @return Buffer number
 Integer nvim_buf_get_number(Buffer buffer, Error *err)
@@ -751,7 +756,7 @@ Integer nvim_buf_get_number(Buffer buffer, Error *err)
 
 /// Gets the full file name for the buffer
 ///
-/// @param buffer     Buffer handle
+/// @param buffer     Buffer handle, or 0 for current buffer
 /// @param[out] err   Error details, if any
 /// @return Buffer name
 String nvim_buf_get_name(Buffer buffer, Error *err)
@@ -769,7 +774,7 @@ String nvim_buf_get_name(Buffer buffer, Error *err)
 
 /// Sets the full file name for a buffer
 ///
-/// @param buffer     Buffer handle
+/// @param buffer     Buffer handle, or 0 for current buffer
 /// @param name       Buffer name
 /// @param[out] err   Error details, if any
 void nvim_buf_set_name(Buffer buffer, String name, Error *err)
@@ -801,7 +806,7 @@ void nvim_buf_set_name(Buffer buffer, String name, Error *err)
 /// Checks if a buffer is valid and loaded. See |api-buffer| for more info
 /// about unloaded buffers.
 ///
-/// @param buffer Buffer handle
+/// @param buffer Buffer handle, or 0 for current buffer
 /// @return true if the buffer is valid and loaded, false otherwise.
 Boolean nvim_buf_is_loaded(Buffer buffer)
   FUNC_API_SINCE(5)
@@ -817,7 +822,7 @@ Boolean nvim_buf_is_loaded(Buffer buffer)
 /// @note Even if a buffer is valid it may have been unloaded. See |api-buffer|
 /// for more info about unloaded buffers.
 ///
-/// @param buffer Buffer handle
+/// @param buffer Buffer handle, or 0 for current buffer
 /// @return true if the buffer is valid, false otherwise.
 Boolean nvim_buf_is_valid(Buffer buffer)
   FUNC_API_SINCE(1)
@@ -849,7 +854,7 @@ void buffer_insert(Buffer buffer,
 
 /// Return a tuple (row,col) representing the position of the named mark
 ///
-/// @param buffer     Buffer handle
+/// @param buffer     Buffer handle, or 0 for current buffer
 /// @param name       Mark name
 /// @param[out] err   Error details, if any
 /// @return (row, col) tuple
@@ -914,7 +919,7 @@ ArrayOf(Integer, 2) nvim_buf_get_mark(Buffer buffer, String name, Error *err)
 /// supported for backwards compatibility, new code should use
 /// |nvim_create_namespace| to create a new empty namespace.
 ///
-/// @param buffer     Buffer handle
+/// @param buffer     Buffer handle, or 0 for current buffer
 /// @param ns_id      namespace to use or -1 for ungrouped highlight
 /// @param hl_group   Name of the highlight group to use
 /// @param line       Line to highlight (zero-indexed)
@@ -964,7 +969,7 @@ Integer nvim_buf_add_highlight(Buffer buffer,
 /// To clear the namespace in the entire buffer, pass in 0 and -1 to
 /// line_start and line_end respectively.
 ///
-/// @param buffer     Buffer handle
+/// @param buffer     Buffer handle, or 0 for current buffer
 /// @param ns_id      Namespace to clear, or -1 to clear all namespaces.
 /// @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
@@ -997,7 +1002,7 @@ void nvim_buf_clear_namespace(Buffer buffer,
 ///
 /// @deprecated use |nvim_buf_clear_namespace|.
 ///
-/// @param buffer     Buffer handle
+/// @param buffer     Buffer handle, or 0 for current buffer
 /// @param ns_id      Namespace 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
@@ -1031,7 +1036,7 @@ void nvim_buf_clear_highlight(Buffer buffer,
 /// As a shorthand, `ns_id = 0` can be used to create a new namespace for the
 /// virtual text, the allocated id is then returned.
 ///
-/// @param buffer     Buffer handle
+/// @param buffer     Buffer handle, or 0 for current buffer
 /// @param ns_id      Namespace to use or 0 to create a namespace,
 ///                   or -1 for a ungrouped annotation
 /// @param line       Line to annotate with virtual text (zero-indexed)
diff --git a/src/nvim/api/ui.c b/src/nvim/api/ui.c
index 93502d7306..d50a91f261 100644
--- a/src/nvim/api/ui.c
+++ b/src/nvim/api/ui.c
@@ -29,8 +29,8 @@ typedef struct {
   uint64_t channel_id;
   Array buffer;
 
-  int hl_id;  // current higlight for legacy put event
-  Integer cursor_row, cursor_col;  // Intended visibule cursor position
+  int hl_id;  // Current highlight for legacy put event.
+  Integer cursor_row, cursor_col;  // Intended visible cursor position.
 
   // Position of legacy cursor, used both for drawing and visible user cursor.
   Integer client_row, client_col;
@@ -264,20 +264,22 @@ static void ui_set_option(UI *ui, bool init, String name, Object value,
 ///
 /// On invalid grid handle, fails with error.
 ///
+/// @param channel_id
 /// @param grid    The handle of the grid to be changed.
 /// @param width   The new requested width.
 /// @param height  The new requested height.
+/// @param[out] err Error details, if any
 void nvim_ui_try_resize_grid(uint64_t channel_id, Integer grid, Integer width,
-                             Integer height, Error *error)
+                             Integer height, Error *err)
   FUNC_API_SINCE(6) FUNC_API_REMOTE_ONLY
 {
   if (!pmap_has(uint64_t)(connected_uis, channel_id)) {
-    api_set_error(error, kErrorTypeException,
+    api_set_error(err, kErrorTypeException,
                   "UI not attached to channel: %" PRId64, channel_id);
     return;
   }
 
-  ui_grid_resize((handle_T)grid, (int)width, (int)height, error);
+  ui_grid_resize((handle_T)grid, (int)width, (int)height, err);
 }
 
 /// Pushes data into UI.UIData, to be consumed later by remote_ui_flush().
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)
diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c
index 2204170aab..a68ae805e8 100644
--- a/src/nvim/api/window.c
+++ b/src/nvim/api/window.c
@@ -345,6 +345,7 @@ 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 channel_id
 /// @param window   Window handle
 /// @param name     Option name
 /// @param value    Option value
@@ -527,9 +528,7 @@ Dictionary nvim_win_get_config(Window window, Error *err)
 /// @param force    Behave like `:close!` The last window of a buffer with
 ///                 unwritten changes can be closed. The buffer will become
 ///                 hidden, even if 'hidden' is not set.
-///
 /// @param[out] err Error details, if any
-/// @return Window number
 void nvim_win_close(Window window, Boolean force, Error *err)
   FUNC_API_SINCE(6)
 {
diff --git a/src/nvim/event/stream.h b/src/nvim/event/stream.h
index e713323f5c..694dab6568 100644
--- a/src/nvim/event/stream.h
+++ b/src/nvim/event/stream.h
@@ -13,7 +13,7 @@ typedef struct stream Stream;
 /// Type of function called when the Stream buffer is filled with data
 ///
 /// @param stream The Stream instance
-/// @param rbuffer The associated RBuffer instance
+/// @param buf The associated RBuffer instance
 /// @param count Number of bytes that was read.
 /// @param data User-defined data
 /// @param eof If the stream reached EOF.
@@ -23,7 +23,7 @@ typedef void (*stream_read_cb)(Stream *stream, RBuffer *buf, size_t count,
 /// Type of function called when the Stream has information about a write
 /// request.
 ///
-/// @param wstream The Stream instance
+/// @param stream The Stream instance
 /// @param data User-defined data
 /// @param status 0 on success, anything else indicates failure
 typedef void (*stream_write_cb)(Stream *stream, void *data, int status);
diff --git a/src/nvim/ex_docmd.c b/src/nvim/ex_docmd.c
index 0ea383dbb6..fbe41f9914 100644
--- a/src/nvim/ex_docmd.c
+++ b/src/nvim/ex_docmd.c
@@ -78,7 +78,7 @@
 static int quitmore = 0;
 static int ex_pressedreturn = FALSE;
 
-/* whether ":lcd" was produced for a session */
+/// Whether ":lcd" or ":tcd" was produced for a session.
 static int did_lcd;
 
 typedef struct ucmd {
diff --git a/src/nvim/ui_compositor.c b/src/nvim/ui_compositor.c
index 50432dd119..e24ab11a3a 100644
--- a/src/nvim/ui_compositor.c
+++ b/src/nvim/ui_compositor.c
@@ -3,6 +3,8 @@
 
 // Compositor: merge floating grids with the main grid for display in
 // TUI and non-multigrid UIs.
+//
+// Layer-based compositing: https://en.wikipedia.org/wiki/Digital_compositing
 
 #include <assert.h>
 #include <stdbool.h>
@@ -104,6 +106,9 @@ bool ui_comp_should_draw(void)
   return composed_uis != 0 && valid_screen;
 }
 
+/// Places `grid` at (col,row) position with (width * height) size.
+/// Adds `grid` as the top layer if it is a new layer.
+///
 /// TODO(bfredl): later on the compositor should just use win_float_pos events,
 /// though that will require slight event order adjustment: emit the win_pos
 /// events in the beginning of  update_screen(0), rather than in ui_flush()
diff --git a/src/nvim/ui_compositor.h b/src/nvim/ui_compositor.h
index b3780db532..70e01c3a21 100644
--- a/src/nvim/ui_compositor.h
+++ b/src/nvim/ui_compositor.h
@@ -1,5 +1,3 @@
-// Bridge for communication between a UI thread and nvim core.
-// Used by the built-in TUI and libnvim-based UIs.
 #ifndef NVIM_UI_COMPOSITOR_H
 #define NVIM_UI_COMPOSITOR_H