doc [ci skip]

closes #9719

README.md

@@ -2,9 +2,8 @@
 
 [Wiki](https://github.com/neovim/neovim/wiki) |
 [Documentation](https://neovim.io/doc) |
-[Twitter](https://twitter.com/Neovim) |
+[Chat/Discussion](https://gitter.im/neovim/neovim) |
-[Community](https://neovim.io/community/) |
+[Twitter](https://twitter.com/Neovim)
-[Gitter **Chat**](https://gitter.im/neovim/neovim)
 
 [![Travis build status](https://travis-ci.org/neovim/neovim.svg?branch=master)](https://travis-ci.org/neovim/neovim)
 [![AppVeyor build status](https://ci.appveyor.com/api/projects/status/urdqjrik5u521fac/branch/master?svg=true)](https://ci.appveyor.com/project/neovim/neovim/branch/master)
@@ -34,9 +33,8 @@ Features
 
 - Modern [GUIs](https://github.com/neovim/neovim/wiki/Related-projects#gui)
 - [API access](https://github.com/neovim/neovim/wiki/Related-projects#api-clients)
-  from any language including C/C++, C#, Clojure, D, Elixir, Lisp, Go,
+  from any language including C/C++, C#, Clojure, D, Elixir, Go, Haskell, Java,
-  Haskell, Java, JavaScript/Node.js, Julia, Lisp, Lua, Perl, Python, Racket,
+  JavaScript/Node.js, Julia, Lisp, Lua, Perl, Python, Racket, Ruby, Rust
-  Ruby, Rust
 - Embedded, scriptable [terminal emulator](https://neovim.io/doc/user/nvim_terminal_emulator.html)
 - Asynchronous [job control](https://github.com/neovim/neovim/pull/2247)
 - [Shared data (shada)](https://github.com/neovim/neovim/pull/2506) among multiple editor instances
@@ -51,8 +49,8 @@ Install from package
 Pre-built packages for Windows, macOS, and Linux are found on the
 [Releases](https://github.com/neovim/neovim/releases/) page.
 
-Managed packages are in [Homebrew], [Debian], [Ubuntu], [Fedora], [Arch Linux], [Gentoo],
+[Managed packages] are in Homebrew, [Debian], [Ubuntu], [Fedora], [Arch Linux],
-and [more](https://github.com/neovim/neovim/wiki/Installing-Neovim)!
+[Gentoo], and more!
 
 Install from source
 -------------------
@@ -144,7 +142,7 @@ See `LICENSE` for details.
 [nvim-features]: https://neovim.io/doc/user/vim_diff.html#nvim-features
 [Roadmap]: https://neovim.io/roadmap/
 [advanced UIs]: https://github.com/neovim/neovim/wiki/Related-projects#gui
-[Homebrew]: https://github.com/neovim/homebrew-neovim#installation
+[Managed packages]: https://github.com/neovim/neovim/wiki/Installing-Neovim#install-from-package
 [Debian]: https://packages.debian.org/testing/neovim
 [Ubuntu]: http://packages.ubuntu.com/search?keywords=neovim
 [Fedora]: https://apps.fedoraproject.org/packages/neovim

runtime/doc/autocmd.txt

@@ -43,7 +43,7 @@ effects.  Be careful not to destroy your text.
 :au[tocmd] [group] {event} {pat} [++once] [++nested] {cmd}
 			Add {cmd} to the list of commands that Vim will
 			execute automatically on {event} for a file matching
-			{pat} |autocmd-patterns|.
+			{pat} |autocmd-pattern|.
 			Note: A quote character is seen as argument to the
 			:autocmd and won't start a comment.
 			Nvim always adds {cmd} after existing autocommands so
@@ -358,7 +358,7 @@ Name			triggered by ~
 |CompleteDone|		after Insert mode completion is done
 
 |User|			to be used in combination with ":doautocmd"
-|Signal|		after the nvim process received a signal
+|Signal|		after Nvim receives a signal
 
 
 
@@ -870,27 +870,27 @@ MenuPopupChanged 					*MenuPopupChanged*
 				It is not allowed to change the text |textlock|.
 
 							*OptionSet*
-OptionSet			After setting an option.  The pattern is
+OptionSet			After setting an option (except during
-				matched against the long option name.
+				|startup|).  The |autocmd-pattern| is matched
-				The |v:option_old| variable indicates the
+				against the long option name.
-				old option value, |v:option_new| variable
+				|v:option_old| indicates the old option value,
-				indicates the newly set value, the
+				|v:option_new| indicates the new value,
-				|v:option_type| variable indicates whether
+				|v:option_type| indicates whether it's global
-				it's global or local scoped and |<amatch>|
+				or local scoped and |<amatch>| indicates which
-				indicates what option has been set.
+				option was set.
 
 				Usage example: Check for the existence of the
 				directory in the 'backupdir' and 'undodir'
 				options, create the directory if it doesn't
 				exist yet.
 
-				Note: It's a bad idea to reset an option
+				Note: Do not reset the same option during this
-				during this autocommand, this may break a
+				autocommand, that may break plugins. You can
-				plugin. You can always use `:noa` to prevent
+				always use |:noautocmd| to prevent triggering
-				triggering this autocommand.
+				OptionSet.
 
-				When using |:set| in the autocommand the event
+				Recursion is ignored, thus |:set| in the
-				is not triggered again.
+				autocommand does not trigger OptionSet again.
 
 							*QuickFixCmdPre*
 QuickFixCmdPre			Before a quickfix command is run (|:make|,
@@ -943,10 +943,11 @@ ShellCmdPost			After executing a shell command with |:!cmd|,
 				For non-blocking shell commands, see
 				|job-control|.
 							*Signal*
-Signal				After the nvim process received a signal.
+Signal				After Nvim receives a signal. The pattern is
-				The pattern is matched against the name of the
+				matched against the signal name. Only
-				received signal. Only "SIGUSR1" is supported.
+				"SIGUSR1" is supported.  Example: >
-							*ShellFilterPost*
+				    autocmd Signal SIGUSR1 call some#func()
+<							*ShellFilterPost*
 ShellFilterPost			After executing a shell command with
 				":{range}!cmd", ":w !cmd" or ":r !cmd".
 				Can be used to check for any changed files.
@@ -1123,7 +1124,7 @@ WinNew				When a new window was created.  Not done for
 				Before a WinEnter event.
 
 ==============================================================================
-6. Patterns					*autocmd-patterns* *{pat}*
+6. Patterns					*autocmd-pattern* *{pat}*
 
 The {pat} argument can be a comma separated list.  This works as if the
 command was given with each pattern separately.  Thus this command: >

runtime/doc/eval.txt

@@ -3782,7 +3782,7 @@ function({name} [, {arglist}] [, {dict}])
 		same function.
 
 		When {arglist} or {dict} is present this creates a partial.
-		That mans the argument list and/or the dictionary is stored in
+		That means the argument list and/or the dictionary is stored in
 		the Funcref and will be used when the Funcref is called.
 
 		The arguments are passed to the function in front of other

runtime/doc/if_lua.txt

@@ -16,11 +16,11 @@ an idea of what lurks beneath: >
 
     :lua print(vim.inspect(package.loaded))
 
-Nvim includes a "standard library" |lua-stdlib| for Lua.  This library
+Nvim includes a "standard library" |lua-stdlib| for Lua.  It complements the
-complements the Nvim editor |functions| and Ex commands (the editor "stdlib"),
+"editor stdlib" (|functions| and Ex commands) and the |API|, all of which can
-which can also be used from Lua code.
+be used from Lua code.
 
-Nvim resolves module conflicts by "last wins".  For example if both of these
+Module conflicts are resolved by "last wins".  For example if both of these
 are on 'runtimepath':
     runtime/lua/foo.lua
     ~/.config/nvim/lua/foo.lua
@@ -260,9 +260,9 @@ position are restricted when the command is executed in the |sandbox|.
 ==============================================================================
 vim.*							*lua-vim* *lua-stdlib*
 
-The "standard library" (stdlib) of Nvim Lua is the `vim` module, which exposes
+The Nvim Lua "standard library" (stdlib) is the `vim` module, which exposes
-various functions and sub-modules.  The module is implicitly loaded, thus
+various functions and sub-modules.  It is always loaded, thus require("vim")
-require("vim") is unnecessary.
+is unnecessary.
 
 You can peek at the module properties: >
 
@@ -288,7 +288,7 @@ To find documentation on e.g. the "deepcopy" function: >
 
     :help vim.deepcopy
 
-Note: Underscore-prefixed functions (e.g. "_os_proc_children") are
+Note that underscore-prefixed functions (e.g. "_os_proc_children") are
 internal/private and must not be used by plugins.
 
 ------------------------------------------------------------------------------

runtime/doc/map.txt

@@ -227,14 +227,14 @@ should not either insert or change the v:char.
 
 Be very careful about side effects!  The expression is evaluated while
 obtaining characters, you may very well make the command dysfunctional.
-For this reason the following is blocked:
+Therefore the following is blocked for <expr> mappings:
 - Changing the buffer text |textlock|.
 - Editing another buffer.
 - The |:normal| command.
 - Moving the cursor is allowed, but it is restored afterwards.
 - If the cmdline is changed, the old text and cursor position are restored.
 If you want the mapping to do any of these let the returned characters do
-that. Or use a |<Cmd>| mapping (which doesn't have these restrictions).
+that. (Or use a |<Cmd>| mapping instead.)
 
 You can use getchar(), it consumes typeahead if there is any. E.g., if you
 have these mappings: >
@@ -274,9 +274,9 @@ Using 0x80 as a single byte before other text does not work, it will be seen
 as a special key.
 
 						*<Cmd>* *:map-cmd*
-The <Cmd> pseudokey may be used to define a "command mapping", which executes
+The <Cmd> pseudokey begins a "command mapping", which executes the command
-the command directly (without changing modes, etc.).  Where you might use
+directly (without changing modes).  Where you might use ":...<CR>" in the
-":...<CR>" in the {lhs} of a mapping, you can instead use "<Cmd>...<CR>".
+{lhs} of a mapping, you can instead use "<Cmd>...<CR>".
 Example: >
 	noremap x <Cmd>echo mode(1)<cr>
 <
@@ -284,17 +284,21 @@ This is more flexible than `:<C-U>` in visual and operator-pending mode, or
 `<C-O>:` in insert-mode, because the commands are executed directly in the
 current mode (instead of always going to normal-mode).  Visual-mode is
 preserved, so tricks with |gv| are not needed.  Commands can be invoked
-directly in cmdline-mode (which otherwise would require timer hacks).
+directly in cmdline-mode (which would otherwise require timer hacks).
-
-Because <Cmd> avoids mode-changes (unlike ":") it does not trigger
-|CmdlineEnter| and |CmdlineLeave| events. This helps performance.
 
 Unlike <expr> mappings, there are no special restrictions on the <Cmd>
 command: it is executed as if an (unrestricted) |autocmd| was invoked or an
 async event event was processed.
 
-In select-mode, |:map| and |:vmap| command mappings are executed in
+Note:
-visual-mode.  Use |:smap| to handle select-mode.
+- Because <Cmd> avoids mode-changes (unlike ":") it does not trigger
+  |CmdlineEnter| and |CmdlineLeave| events. This helps performance.
+- For the same reason, |keycodes| like <C-R><C-W> are interpreted in the
+  context of the current mode, not cmdline-mode!  Thus <C-R><C-W> in a
+  :nnoremap (normal-mode) mapping does the normal-mode function of <C-R> and
+  <C-W> rather than the cmdline-mode <C-R><C-W> chord.
+- In select-mode, |:map| and |:vmap| command mappings are executed in
+  visual-mode.  Use |:smap| to handle select-mode.
 
 							*E5520*
 <Cmd> commands must terminate, that is, they must be followed by <CR> in the

runtime/doc/nvim.txt

@@ -8,14 +8,14 @@ Nvim							   *nvim* *nvim-intro*
 
 Nvim is based on Vim by Bram Moolenaar.
 
+If you already use Vim see |nvim-from-vim| for a quickstart.
 If you are new to Vim, try the 30-minute tutorial: >
+
     :Tutor<Enter>
 
-If you already use Vim see |nvim-from-vim| for a quickstart.
+Nvim is emphatically a fork of Vim, not a clone: compatibility with Vim
-
+(especially editor and VimL features) is maintained where possible. See
-Nvim is emphatically a fork of Vim, not a clone: compatibility with Vim is
+|vim-differences| for the complete reference of differences from Vim.
-maintained where possible. See |vim_diff.txt| for the complete reference of
-differences from Vim.
 
 				      Type |gO| to see the table of contents.
 

runtime/doc/options.txt

@@ -694,8 +694,9 @@ A jump table for the options with a short description can be found at |Q_op|.
 							*'background'* *'bg'*
 'background' 'bg'	string	(default "dark")
 			global
-	When set to "dark" or "light", Nvim will adjust the default color
+	When set to "dark" or "light", adjusts the default color groups for
-	groups for a dark or light background, respectively.
+	that background type.  The |TUI| or other UI sets this on startup
+	(triggering |OptionSet|) if it can detect the background color.
 
 	This option does NOT change the background color, it tells Nvim what
 	the "inherited" (terminal/GUI) background looks like.
@@ -878,7 +879,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	A list of file patterns.  When one of the patterns matches with the
 	name of the file which is written, no backup file is created.  Both
 	the specified file name and the full path name of the file are used.
-	The pattern is used like with |:autocmd|, see |autocmd-patterns|.
+	The pattern is used like with |:autocmd|, see |autocmd-pattern|.
 	Watch out for special characters, see |option-backslash|.
 	When $TMPDIR, $TMP or $TEMP is not defined, it is not used for the
 	default value.  "/tmp/*" is only used for Unix.
@@ -1831,9 +1832,9 @@ A jump table for the options with a short description can be found at |Q_op|.
 	name.  See |option-backslash| about using backslashes.
 	This has nothing to do with the |Dictionary| variable type.
 	Where to find a list of words?
-	- On FreeBSD, there is the file "/usr/share/dict/words".
+	- BSD/macOS include the "/usr/share/dict/words" file.
-	- In the Simtel archive, look in the "msdos/linguist" directory.
+	- Try "apt install spell" to get the "/usr/share/dict/words" file on
-	- In "miscfiles" of the GNU collection.
+	  apt-managed systems (Debian/Ubuntu).
 	The use of |:set+=| and |:set-=| is preferred when adding or removing
 	directories from the list.  This avoids problems when a future version
 	uses another default.
@@ -4693,6 +4694,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	  pack/		packages |:packadd|
 	  plugin/	plugin scripts |write-plugin|
 	  print/	files for printing |postscript-print-encoding|
+	  rplugin/	|remote-plugin| scripts
 	  spell/	spell checking files |spell|
 	  syntax/	syntax files |mysyntaxfile|
 	  tutor/	tutorial files |:Tutor|
@@ -6127,8 +6129,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 			global
 	When set: Add 's' flag to 'shortmess' option (this makes the message
 	for a search that hits the start or end of the file not being
-	displayed).  When reset: Remove 's' flag from 'shortmess' option.  {Vi
+	displayed).  When reset: Remove 's' flag from 'shortmess' option.
-	shortens a lot of messages}
 
 						*'textwidth'* *'tw'*
 'textwidth' 'tw'	number	(default 0)
@@ -6506,7 +6507,7 @@ A jump table for the options with a short description can be found at |Q_op|.
 	patterns is ignored when expanding |wildcards|, completing file or
 	directory names, and influences the result of |expand()|, |glob()| and
 	|globpath()| unless a flag is passed to disable this.
-	The pattern is used like with |:autocmd|, see |autocmd-patterns|.
+	The pattern is used like with |:autocmd|, see |autocmd-pattern|.
 	Also see 'suffixes'.
 	Example: >
 		:set wildignore=*.o,*.obj

runtime/doc/remote_plugin.txt

@@ -122,10 +122,10 @@ the example, say the Java plugin is a semantic completion engine for Java code.
 If it defines the autocommand "BufEnter *.java", then the Java host is spawned
 only when Nvim loads a buffer matching "*.java".
 
-If the explicit call to |:UpdateRemotePlugins| seems incovenient, try to see it
+If the explicit call to |:UpdateRemotePlugins| seems inconvenient, try to see
-like this: It's a way to provide IDE capabilities in Nvim while still keeping
+it like this: It's a way to provide IDE capabilities in Nvim while still
-it fast and lightweight for general use. It's also analogous to the |:helptags|
+keeping it fast and lightweight for general use. It's also analogous to the
-command.
+|:helptags| command.
 
 						*$NVIM_RPLUGIN_MANIFEST*
 Unless $NVIM_RPLUGIN_MANIFEST is set the manifest will be written to a file

runtime/doc/usr_43.txt

@@ -94,7 +94,7 @@ unless it was set already.  This will make sure that 'filetype' isn't set
 twice.
 
 You can use many different patterns to match the name of your file.  Directory
-names can also be included.  See |autocmd-patterns|.  For example, the files
+names can also be included.  See |autocmd-pattern|.  For example, the files
 under "/usr/share/scripts/" are all "ruby" files, but don't have the expected
 file name extension.  Adding this to the example above: >
 

runtime/doc/vim_diff.txt

@@ -6,8 +6,9 @@
 
 Differences between Nvim and Vim			       *vim-differences*
 
-Nvim differs from Vim in many ways, big and small.  This document is
+Nvim differs from Vim in many ways, although editor and VimL features are
-a complete and centralized reference of those differences.
+mostly identical.  This document is a complete and centralized reference of
+the differences.
 
 				      Type |gO| to see the table of contents.
 

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)

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
+  int hl_id;  // Current highlight for legacy put event.
-  Integer cursor_row, cursor_col;  // Intended visibule cursor position
+  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().

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
+/// Non-blocking: does not wait on any result, but queues the event to be
-/// queues the event to be processed soon by the event loop.
+/// 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
+/// Identifies the client. Can be called more than once; subsequent calls
-/// calls will remove earlier info, which should be resent if it is still
+/// remove earlier info, which should be included by the caller if it is
-/// valid. (This could happen if a library first identifies the channel, and a
+/// 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 channel_id
-/// @param version  Dictionary describing the version, with the following
+/// @param name Short name for the connected client
-///                 possible keys (all optional)
+/// @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
+/// @param type Must be one of the following values. Client libraries should
-///             use "remote" if the library user hasn't specified other value.
+///             default to "remote" unless overridden by the user.
-///     - "remote" remote client that connected to nvim.
+///     - "remote" remote client connected to Nvim.
 ///     - "ui" gui frontend
-///     - "embedder" application using nvim as a component, for instance
+///     - "embedder" application using Nvim as a component (for example,
-///                  IDE/editor implementing a vim mode.
+///                  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.
+///                of 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
+/// @param attributes Arbitrary string:string map of informal client properties.
-///                   define their own keys, but the following are suggested:
+///     Suggested keys:
-///     - "website" Website of client (for instance github repository)
+///     - "website": Client homepage URL (e.g. GitHub repository)
-///     - "license" Informal description of the license, such as "Apache 2",
+///     - "license": License description ("Apache 2", "GPLv3", "MIT", …)
-///                 "GPLv3" or "MIT"
+///     - "logo":    URI or path to image, preferably small logo or icon.
-///     - "logo"    URI or path to image, preferably small logo or icon.
+///                  .png or .svg format is preferred.
-///                 .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
+/// @returns Dictionary describing a channel, with these keys:
-/// following keys:
+///    - "stream"  the stream underlying the channel
-///     - "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.
+///              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
+/// @param[out] err Validation error details (malformed `calls` parameter),
-/// itself, i.e. malformed `calls` parameter. Errors from called methods will
+///             if any. Errors from batched calls are given in the return value.
-/// be indicated in the return value, see below.
 ///
-/// @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]  expr  Expression to parse. Always treated as a single line.
-/// @param[in]  flags  Flags:
+/// @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:
+/// @return
-///
+///      - AST: top-level dictionary with these keys:
-///         "error": Dictionary with error, present only if parser saw some
+///        - "error": Dictionary with error, present only if parser saw some
-///                  error. Contains the following keys:
+///                 error. Contains the following keys:
-///
+///          - "message": String, error message in printf format, translated.
-///           "message": String, error message in printf format, translated.
+///                       Must contain exactly one "%.*s".
-///                      Must contain exactly one "%.*s".
+///          - "arg": String, error message argument.
-///           "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.
-///         "len": Amount of bytes successfully parsed. With flags equal to ""
+///                 (“Sucessfully parsed” here means “participated in AST
-///                that should be equal to the length of expr string.
+///                  creation”, not “till the first error”.)
-///
+///        - "ast": AST, either nil or a dictionary with these keys:
-///                @note: “Sucessfully parsed” here means “participated in AST
+///          - "type": node type, one of the value names from ExprASTNodeType
-///                       creation”, not “till the first error”.
+///                    stringified without "kExprNode" prefix.
-///
+///          - "start": a pair [line, column] describing where node is "started"
-///         "ast": AST, either nil or a dictionary with these keys:
+///                     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
-///           "type": node type, one of the value names from ExprASTNodeType
+///                     present yet). Both elements are Integers.
-///                   stringified without "kExprNode" prefix.
+///          - "len": “length” of the node. This and "start" are there for
-///           "start": a pair [line, column] describing where node is “started”
+///                   debugging purposes primary (debugging parser and providing
-///                    where "line" is always 0 (will not be 0 if you will be
+///                   debug information).
-///                    using nvim_parse_viml() on e.g. ":let", but that is not
+///          - "children": a list of nodes described in top/"ast". There always
-///                    present yet). Both elements are Integers.
+///                        is zero, one or two children, key will not be present
-///           "len": “length” of the node. This and "start" are there for
+///                        if node has no children. Maximum number of children
-///                  debugging purposes primary (debugging parser and providing
+///                        may be found in node_maxchildren array.
-///                  debug information).
+///      - Local values (present only for certain nodes):
-///           "children": a list of nodes described in top/"ast". There always
+///        - "scope": a single Integer, specifies scope for "Option" and
-///                       is zero, one or two children, key will not be present
+///                   "PlainIdentifier" nodes. For "Option" it is one of
-///                       if node has no children. Maximum number of children
+///                   ExprOptScope values, for "PlainIdentifier" it is one of
-///                       may be found in node_maxchildren array.
+///                   ExprVarScope values.
-///
+///        - "ident": identifier (without scope, if any), present for "Option",
-///           Local values (present only for certain nodes):
+///                   "PlainIdentifier", "PlainKey" and "Environment" nodes.
-///
+///        - "name": Integer, register name (one character) or -1. Only present
-///           "scope": a single Integer, specifies scope for "Option" and
+///                for "Register" nodes.
-///                    "PlainIdentifier" nodes. For "Option" it is one of
+///        - "cmp_type": String, comparison type, one of the value names from
-///                    ExprOptScope values, for "PlainIdentifier" it is one of
+///                      ExprComparisonType, stringified without "kExprCmp"
-///                    ExprVarScope values.
+///                      prefix. Only present for "Comparison" nodes.
-///           "ident": identifier (without scope, if any), present for "Option",
+///        - "ccs_strategy": String, case comparison strategy, one of the
-///                    "PlainIdentifier", "PlainKey" and "Environment" nodes.
+///                          value names from ExprCaseCompareStrategy,
-///           "name": Integer, register name (one character) or -1. Only present
+///                          stringified without "kCCStrategy" prefix. Only
-///                   for "Register" nodes.
+///                          present for "Comparison" nodes.
-///           "cmp_type": String, comparison type, one of the value names from
+///        - "augmentation": String, augmentation type for "Assignment" nodes.
-///                       ExprComparisonType, stringified without "kExprCmp"
+///                          Is either an empty string, "Add", "Subtract" or
-///                       prefix. Only present for "Comparison" nodes.
+///                          "Concat" for "=", "+=", "-=" or ".=" respectively.
-///           "ccs_strategy": String, case comparison strategy, one of the
+///        - "invert": Boolean, true if result of comparison needs to be
-///                           value names from ExprCaseCompareStrategy,
+///                    inverted. Only present for "Comparison" nodes.
-///                           stringified without "kCCStrategy" prefix. Only
+///        - "ivalue": Integer, integer value for "Integer" nodes.
-///                           present for "Comparison" nodes.
+///        - "fvalue": Float, floating-point value for "Float" nodes.
-///           "augmentation": String, augmentation type for "Assignment" nodes.
+///        - "svalue": String, value for "SingleQuotedString" and
-///                           Is either an empty string, "Add", "Subtract" or
+///                    "DoubleQuotedString" nodes.
-///                           "Concat" for "=", "+=", "-=" or ".=" respectively.
+/// @param[out] err Error details, if any
-///           "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.
 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
+/// @return
-///
+///   Array of UI dictionaries, each with these keys:
-/// Each dictionary has the following keys:
+///       - "height"  requested height of the UI
-///     - "height"  requested height of the UI
+///       - "width"   requested width of the UI
-///     - "width"   requested width of the UI
+///       - "rgb"     whether the UI uses rgb colors (false implies cterm colors)
-///     - "rgb"     whether the UI uses rgb colors (false implies cterm colors)
+///       - "ext_..." Requested UI extensions, see |ui-options|
-///     - "ext_..." Requested UI extensions, see |ui-options|
+///       - "chan"    Channel id of remote UI (not present for TUI)
-///     - "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)

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)
 {

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);

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 {

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()

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
 

test/functional/ui/screen.lua

@@ -259,22 +259,19 @@ local ext_keys = {
   'messages', 'showmode', 'showcmd', 'ruler', 'float_pos',
 }
 
--- Asserts that the screen state eventually matches an expected state
+-- Asserts that the screen state eventually matches an expected state.
 --
--- This function can either be called with the positional forms
+-- Can be called with positional args:
---
+--    screen:expect(grid, [attr_ids, attr_ignore])
---  screen:expect(grid, [attr_ids, attr_ignore])
+--    screen:expect(condition)
---  screen:expect(condition)
+-- or keyword args (supports more options):
---
+--    screen:expect{grid=[[...]], cmdline={...}, condition=function() ... end}
--- or to use additional arguments (or grid and condition at the same time)
--- the keyword form has to be used:
---
--- screen:expect{grid=[[...]], cmdline={...}, condition=function() ... end}
 --
 --
 -- grid:        Expected screen state (string). Each line represents a screen
 --              row. Last character of each row (typically "|") is stripped.
 --              Common indentation is stripped.
+--              Lines containing only "{IGNORE}|" are skipped.
 -- attr_ids:    Expected text attributes. Screen rows are transformed according
 --              to this table, as follows: each substring S composed of
 --              characters having the same attributes will be substituted by