Merge pull request #9871 from justinmk/doc

9 files changed, 180 insertions, 146 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index c8b9dd5fad..b2e37a6d60 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -206,17 +206,15 @@ Highlights are registered using the |nvim_buf_add_highlight()| function. If an
 external highlighter plugin wants to add many highlights in a batch,
 performance can be improved by calling |nvim_buf_add_highlight()| as an
 asynchronous notification, after first (synchronously) reqesting a source id.
-Example using the Nvim python-client:
+
+Example using the Python API client (|pynvim|):
 >
     src = vim.new_highlight_source()
-
     buf = vim.current.buffer
     for i in range(5):
         buf.add_highlight("String",i,0,-1,src_id=src)
-
-    # some time later
-
-    buf.clear_highlight(src)
+    # some time later ...
+    buf.clear_namespace(src)
 <
 If the highlights don't need to be deleted or updated, just pass -1 as
 src_id (this is the default in python). Use |nvim_buf_clear_namespace()| to
@@ -224,13 +222,12 @@ clear highlights from a specific source, in a specific line range or the
 entire buffer by passing in the line range 0, -1 (the latter is the default in
 python as used above).
 
-An example of calling the api from vimscript: >
+Example using the API from Vimscript: >
 
     call nvim_buf_set_lines(0, 0, 0, v:true, ["test text"])
     let src = nvim_buf_add_highlight(0, 0, "String", 1, 0, 4)
     call nvim_buf_add_highlight(0, src, "Identifier", 0, 5, -1)
-
-    " later
+    " some time later ...
     call nvim_buf_clear_namespace(0, src, 0, -1)
 
 
@@ -494,8 +491,6 @@ nvim_set_current_dir({dir})                           *nvim_set_current_dir()*
 nvim_get_current_line()                              *nvim_get_current_line()*
                 Gets the current line.
 
-                Parameters: ~
-
                 Return: ~
                     Current line string
 
@@ -508,8 +503,6 @@ nvim_set_current_line({line})                        *nvim_set_current_line()*
 nvim_del_current_line()                              *nvim_del_current_line()*
                 Deletes the current line.
 
-                Parameters: ~
-
 nvim_get_var({name})                                          *nvim_get_var()*
                 Gets a global (g:) variable.
 
@@ -656,6 +649,7 @@ nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
                 For a general overview of floats, see |api-floatwin|.
 
                 Exactly one of `external` and `relative` must be specified.
+                The `width` and `height` of the new window must be specified.
 
                 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
@@ -697,7 +691,7 @@ nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
                               - `height` : window height (in character cells).
                                 Minimum of 1.
                               - `width` : window width (in character cells).
-                                Minimum of 2.
+                                Minimum of 1.
                               - `row` : row position. Screen cell height are
                                 used as unit. Can be floating point.
                               - `col` : column position. Screen cell width is
@@ -1161,7 +1155,7 @@ nvim_buf_line_count({buffer})                          *nvim_buf_line_count()*
                     Line count, or 0 for unloaded buffer. |api-buffer|
 
 nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
-                Activate updates from this buffer to the current channel.
+                Activates buffer-update events on the channel.
 
                 Parameters: ~
                     {buffer}       Buffer handle, or 0 for current buffer
@@ -1180,7 +1174,7 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
                     True.
 
 nvim_buf_detach({buffer})                                  *nvim_buf_detach()*
-                Deactivate updates from this buffer to the current channel.
+                Deactivates buffer-update events on the channel.
 
                 Parameters: ~
                     {buffer}  Buffer handle, or 0 for current buffer
@@ -1738,10 +1732,27 @@ nvim_tabpage_is_valid({tabpage})                     *nvim_tabpage_is_valid()*
 UI Functions                                                          *api-ui*
 
 nvim_ui_attach({width}, {height}, {options})                *nvim_ui_attach()*
-                TODO: Documentation
+                Activates UI events on the channel.
+
+                Entry point of all UI clients. Allows |--embed| to continue
+                startup. Implies that the client is ready to show the UI. Adds
+                the client to the list of UIs. |nvim_list_uis()|
+
+                Note:
+                    If multiple UI clients are attached, the global screen
+                    dimensions degrade to the smallest client. E.g. if client
+                    A requests 80x40 but client B requests 200x100, the global
+                    screen has size 80x40.
+
+                Parameters: ~
+                    {width}    Requested screen columns
+                    {height}   Requested screen rows
+                    {options}  |ui-options| map
 
 nvim_ui_detach()                                            *nvim_ui_detach()*
-                TODO: Documentation
+                Deactivates UI events on the channel.
+
+                Removes the client from the list of UIs. |nvim_list_uis()|
 
 nvim_ui_try_resize({width}, {height})                   *nvim_ui_try_resize()*
                 TODO: Documentation
diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 9e74efabe0..9272c0693e 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -12,6 +12,9 @@ updated.
 
 ==============================================================================
 
+API ~
+*nvim_buf_clear_highlight()*	Use |nvim_buf_clear_namespace()| instead.
+
 Commands ~
 *:rv*
 *:rviminfo*		Deprecated alias to |:rshada| command.
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index d400df6b7d..9e2994ae2e 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1502,7 +1502,8 @@ v:dying		Normally zero.	When a deadly signal is caught it's set to
 v:exiting	Exit code, or |v:null| if not exiting. |VimLeave|
 
 					*v:errmsg* *errmsg-variable*
-v:errmsg	Last given error message.  It's allowed to set this variable.
+v:errmsg	Last given error message.
+		Modifiable (can be set).
 		Example: >
 	:let v:errmsg = ""
 	:silent! next
@@ -1827,7 +1828,8 @@ v:shell_error	Result of the last shell command.  When non-zero, the last
 	:endif
 <
 					*v:statusmsg* *statusmsg-variable*
-v:statusmsg	Last given status message.  It's allowed to set this variable.
+v:statusmsg	Last given status message.
+		Modifiable (can be set).
 
 					*v:stderr* *stderr-variable*
 v:stderr	|channel-id| corresponding to stderr. The value is always 2;
@@ -1893,9 +1895,9 @@ v:termresponse	The escape sequence returned by the terminal for the DA
 v:testing	Must be set before using `test_garbagecollect_now()`.
 
 				*v:this_session* *this_session-variable*
-v:this_session	Full filename of the last loaded or saved session file.  See
-		|:mksession|.  It is allowed to set this variable.  When no
-		session file has been saved, this variable is empty.
+v:this_session	Full filename of the last loaded or saved session file.
+		Empty when no session file has been saved.  See |:mksession|.
+		Modifiable (can be set).
 
 					*v:throwpoint* *throwpoint-variable*
 v:throwpoint	The point where the exception most recently caught and not
@@ -1922,22 +1924,20 @@ v:val		Value of the current item of a |List| or |Dictionary|.	Only
 		|filter()|.  Read-only.
 
 					*v:version* *version-variable*
-v:version	Version number of Vim: Major version number times 100 plus
-		minor version number.  Version 5.0 is 500.  Version 5.1 (5.01)
-		is 501.  Read-only.  "version" also works, for backwards
-		compatibility.
-		Use |has()| to check if a certain patch was included, e.g.: >
-			if has("patch-7.4.123")
-<		Note that patch numbers are specific to the version, thus both
-		version 5.0 and 5.1 may have a patch 123, but these are
-		completely different.
+v:version	Vim version number: major version times 100 plus minor
+		version.  Vim 5.0 is 500, Vim 5.1 is 501.
+		Read-only.
+		Use |has()| to check the Nvim (not Vim) version: >
+			:if has("nvim-0.2.1")
+<
 
 				*v:vim_did_enter* *vim_did_enter-variable*
-v:vim_did_enter	Zero until most of startup is done.  It is set to one just
-		before |VimEnter| autocommands are triggered.
+v:vim_did_enter	0 during startup, 1 just before |VimEnter|.
+		Read-only.
 
 					*v:warningmsg* *warningmsg-variable*
-v:warningmsg	Last given warning message.  It's allowed to set this variable.
+v:warningmsg	Last given warning message.
+		Modifiable (can be set).
 
 					*v:windowid* *windowid-variable*
 v:windowid	Application-specific window "handle" which may be set by any
@@ -4674,8 +4674,8 @@ has({feature})	Returns 1 if {feature} is supported, 0 otherwise.  The
 		{feature} argument is a feature name like "nvim-0.2.1" or
 		"win32", see below.  See also |exists()|.
 
-		Vim's compile-time feature names (prefixed with "+") are not
-		supported because Nvim is always compiled with ALL possible
+		Vim's compile-time feature-names (prefixed with "+") are not
+		recognized because Nvim is always compiled with all possible
 		features. |feature-compile| 
 
 		Feature names can be:
@@ -4704,14 +4704,12 @@ has({feature})	Returns 1 if {feature} is supported, 0 otherwise.  The
 			wsl		WSL (Windows Subsystem for Linux) system
 
 							*has-patch*
-		3.  Vim patches.  The "patch123" feature means that Vim patch
-		    123 has been included.  This does not check the Vim
-		    version, you could check |v:version| for that.
-		    Example: >
+		3.  Vim patch. For example the "patch123" feature means that
+		    Vim patch 123 at the current |v:version| was included: >
 			:if v:version > 602 || v:version == 602 && has("patch148")
 
-<		5.  Vim version. For example the "patch-7.4.237" feature means
-		    that the Vim version is 7.4.237 or later. >
+<		4.  Vim version. For example the "patch-7.4.237" feature means
+		    that Nvim is Vim-compatible to version 7.4.237 or later. >
 			:if has("patch-7.4.237")
 
 
diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt
index 862aa7b750..91a4a3c267 100644
--- a/runtime/doc/msgpack_rpc.txt
+++ b/runtime/doc/msgpack_rpc.txt
@@ -114,17 +114,18 @@ You can also embed an Nvim instance via |jobstart()|, and communicate using
 ==============================================================================
 4. Implementing API clients			*rpc-api-client* *api-client*
 
-"API clients" wrap the Nvim API to provide idiomatic "SDKs" for their
-respective platforms (see |dev-jargon|). You can build a new API client for
-your favorite platform or programming language.
+API clients wrap the Nvim API to provide idiomatic "SDKs" for their respective
+platforms (see |jargon|). You can build a new API client for your favorite
+platform or programming language.
 
-Existing API clients are listed here:
+API clients are listed here:
     https://github.com/neovim/neovim/wiki/Related-projects#api-clients
 
+                                                                      *pynvim*
 The Python client is the reference implementation for API clients. It is
 always up-to-date with the Nvim API, so its source code and test suite are
 authoritative references.
-    https://github.com/neovim/python-client
+    https://github.com/neovim/pynvim
 
 API client implementation guidelines ~
 
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index a8ba64fda8..771165c361 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -195,34 +195,33 @@ argument.
 -E		Start Nvim in Ex mode |gQ|.
 
 		If stdin is not a TTY:
-		  -e reads stdin as Ex commands.
+		  -e reads/executes stdin as Ex commands.
 		  -E reads stdin as text (into buffer 1).
 
-							*-es* *-Es*
--es							*-s-ex* *silent-mode*
--Es		Silent or batch mode: execute Ex commands from a file instead
-		of a terminal.  Special case of |-s| (which takes an argument
-		while "-es" doesn't).  Disables most prompts, messages,
-		warnings and errors.
-		Output of these commands is displayed (to stdout):
+-es						*-es* *-Es* *-s-ex* *silent-mode*
+-Es		Silent or batch mode.  Special case of |-s| (which takes an
+		argument while "-es" doesn't).  Disables most prompts,
+		messages, warnings and errors.
+
+		-es reads/executes stdin as Ex commands. >
+			printf "put ='foo'\n%%print\n" | nvim -es
+
+<		-Es reads stdin as text (into buffer 1).  Use |-c| or "+" to
+		send commands. >
+			printf "foo\n" | nvim -Es +"%print"
+
+<		Output of these commands is displayed (to stdout):
 			:print
 			:list
 			:number
-			:set      to display option values.
-		When 'verbose' is set messages are printed to stderr, e.g.: >
+			:set      (to display option values)
+		When 'verbose' is set messages are printed to stderr. >
 			echo foo | nvim -V1 -es
-<
-		User |init.vim| is skipped (unless given with |-u|).
-		Swap file is skipped (like |-n|).
-		|$TERM| is not used.
 
-		If stdin is not a TTY:
-		  -es reads stdin as Ex commands.
-		  -Es reads stdin as text (into buffer 1).
+<		User |init.vim| is skipped (unless given with |-u|).
+		Swap file is skipped (like |-n|).
+		User |shada| is loaded (unless "-i NONE" is given).
 
-		Example: >
-			printf "put ='foo'\n%%print\n" | nvim -es
-<
 							*-b*
 -b		Binary mode.  File I/O will only recognize <NL> to separate
 		lines.  The 'expandtab' option will be reset.  The 'textwidth'
@@ -355,35 +354,33 @@ argument.
 --embed		Use stdin/stdout as a msgpack-RPC channel, so applications can
 		embed and control Nvim via the |rpc-api|.
 
-		By default nvim will wait for the embedding process to call
-		`nvim_ui_attach` before sourcing startup files and reading
-		buffers.  This is so that UI can show startup messages and
-		possible swap file dialog for the first loaded file.  The
-		process can do requests before the `nvim_ui_attach`, for
-		instance a `nvim_get_api_info` call so that UI features can be
-		safely detected by the UI before attaching.
-
-		See |ui-startup| for more information about UI startup.
-
-		To embed nvim without using the UI protocol, `--headless` should
-		be supplied together with `--embed`. Then initialization is
-		performed without waiting for an UI. This is also equivalent
-		to the following alternative: >
-			nvim --headless --cmd "call stdioopen({'rpc': v:true})"
-<
-		See also |channel-stdio|.
+		Waits for the client ("embedder") to call |nvim_ui_attach()|
+		before sourcing startup files and reading buffers, so that UIs
+		can deterministically handle (display) early messages,
+		dialogs, etc.  The client can do other requests before
+		`nvim_ui_attach` (e.g. `nvim_get_api_info` for feature-detection).
+		During this pre-startup phase the user config is of course not
+		available (similar to `--cmd`).
+
+		Embedders _not_ using the UI protocol must pass |--headless|: >
+		    nvim --embed --headless
+
+<		Then startup will continue without waiting for `nvim_ui_attach`.
+		This is equivalent to: >
+		    nvim --headless --cmd "call stdioopen({'rpc': v:true})"
+
+<		See also: |ui-startup| |channel-stdio|
 
 							*--headless*
---headless 	Start nvim without an UI. The TUI is not used, so stdio
-		can be used as an arbitrary communication channel.
-		|channel-stdio| When used together with `--embed`, do not wait
-		for the embedder to attach an UI.
+--headless 	Start without UI, and do not wait for `nvim_ui_attach`. The
+		builtin TUI is not used, so stdio works as an arbitrary
+		communication channel. |channel-stdio| 
 
 		Also useful for scripting (tests) to see messages that would
 		not be printed by |-es|.
 
 		To detect if a UI is available, check if |nvim_list_uis()| is
-		empty in or after |VimEnter|.
+		empty during or after |VimEnter|.
 
 		To read stdin as text, "-" must be given explicitly:
 		--headless cannot assume that stdin is just text. >
diff --git a/runtime/doc/ui.txt b/runtime/doc/ui.txt
index 98476ea8fa..73eb2210f5 100644
--- a/runtime/doc/ui.txt
+++ b/runtime/doc/ui.txt
@@ -64,7 +64,7 @@ the batch array, nor after a batch not ending with "flush".
 By default, Nvim sends |ui-global| and |ui-grid-old| events; these suffice to
 implement a terminal-like interface. However there are two revisions of the
 grid part of the protocol. The newer revision |ui-linegrid|, enabled by
-`ext_linegrid` option, has a more effecient representation of text (especially
+`ext_linegrid` option, has a more efficient representation of text (especially
 highlighted text), and allows extensions that use multiple grids.
 
 The older revision is available and used by default only for backwards
@@ -83,35 +83,31 @@ for forward-compatibility. |api-contract|
 ==============================================================================
 UI startup							   *ui-startup*
 
-Nvim defines a standard procedure for how an embedding UI should interact with
-the startup phase of Nvim. When spawning the nvim process, use the |--embed| flag
-but not the |--headless| flag. The started Nvim process will pause before loading
-startup files and reading buffers, and give the UI a chance to invoke requests
-to do early initialization. As soon as the UI invokes |nvim_ui_attach()|, the
-startup will continue.
+UI embedders (clients that start Nvim with |--embed| and later call
+|nvim_ui_attach()|) must start Nvim without |--headless|: >
+    nvim --embed
+Nvim will pause before loading startup files and reading buffers, so the UI
+has a chance to invoke requests and do early initialization. Startup will
+continue as soon as the UI invokes |nvim_ui_attach()|.
 
-A simple UI only need to do a single |nvim_ui_attach()| request and then
-be prepared to handle any UI event. A more featureful UI, which might need
+A simple UI only needs to do a single |nvim_ui_attach()| request and then
+prepare to handle any UI event. A more featureful UI, which might need
 additional configuration of the nvim process, should use the following startup
 procedure:
 
-1. Invoke |nvim_get_api_info()|, if this is needed to setup the client library
-   and/or to get the list of supported UI extensions.
-2. At this time, any configuration that should be happen before init.vim
-   loading should be done. Buffers and windows are not available at this
-   point, but this could be used to set |g:| variables visible to init.vim
-3. If the UI wants to do additional setup after the init.vim file was loaded
-   register an autocmd for VimEnter at this point: >
-
-    nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')")
-
-<4.  Now invoke |nvim_ui_attach()|. The UI will need to handle keyboard input
-    at this point, as sourcing init.vim and loading buffers might lead to
-    blocking prompts.
-5.  If step 3 was used, nvim will send a blocking "vimenter" request to the
-    UI. Inside this request handler, the UI can safely do any initialization
-    before entering normal mode, for instance reading variables set by
-    init.vim.
+1. Invoke |nvim_get_api_info()|, if needed to setup the client library and/or
+   to get the list of supported UI extensions.
+2. Do any configuration that should be happen before user config is loaded.
+   Buffers and windows are not available at this point, but this could be used
+   to set |g:| variables visible to init.vim
+3. If the UI wants to do additional setup after user config is loaded,
+   register a VimEnter autocmd: >
+      nvim_command("autocmd VimEnter * call rpcrequest(1, 'vimenter')")
+<4. Now invoke |nvim_ui_attach()|. The UI must handle user input by now:
+   sourcing init.vim and loading buffers might lead to blocking prompts.
+5. If step 3 was used, Nvim will send a blocking "vimenter" request to the UI.
+   Inside this request handler, the UI can safely do any initialization before
+   entering normal mode, for example reading variables set by init.vim.
 
 ==============================================================================
 Global Events							    *ui-global*
@@ -220,7 +216,7 @@ Grid Events (line-based)					  *ui-linegrid*
 
 These events are used if `ext_linegrid` option is set (recommended for all new
 UIs). The biggest change compared to previous revision is to use a single
-event `grid_line` to update the contents of a screen line (where the old
+`grid_line` event to update the contents of a screen line (where the old
 protocol used a combination of cursor, highlight and text events)
 
 Most of these events take a `grid` index as first parameter.  Grid 1 is the
@@ -231,7 +227,7 @@ created.  To enable per-window grids, `ext_multigrid` option should be set (see
 |ui-multigrid|).
 
 Highlight attribute groups are predefined. UIs should maintain a table to map
-numerical highlight `id`:s to the actual attributes.
+numerical highlight ids to the actual attributes.
 
 ["grid_resize", grid, width, height]
 	Resize a `grid`. If `grid` wasn't seen by the client before, a new grid is
@@ -242,12 +238,12 @@ numerical highlight `id`:s to the actual attributes.
 	special colors respectively. `cterm_fg` and `cterm_bg` specifies the
 	default color codes to use in a 256-color terminal.
 
-	The rgb values will always be valid colors, by default. If no
+	The RGB values will always be valid colors, by default. If no
 	colors have been set, they will default to black and white, depending
 	on 'background'. By setting the `ext_termcolors` option, instead
-	-1 will be used for unset colors. This is mostly useful for a
-	TUI implementation, where using the terminal emulators builitn
-	defaults are expected.
+	-1 will be used for unset colors. This is mostly useful for a TUI
+	implementation, where using the terminal builtin ("ANSI") defaults
+	are expected.
 
 	Note: unlike the corresponding events in the first revision, the
 	screen is not always cleared after sending this event. The GUI has to
@@ -275,7 +271,7 @@ numerical highlight `id`:s to the actual attributes.
 	All boolean keys default to false, and will only be sent when they
 	are true.
 
-	Highlights are always transmitted both for both the rgb format and as
+	Highlights are always transmitted both for both the RGB format and as
 	terminal 256-color codes, as the `rgb_attr` and `cterm_attr` parameters
 	respectively. The |ui-rgb| option has no effect effect anymore.
 	Most external UIs will only need to store and use the `rgb_attr`
@@ -284,17 +280,17 @@ numerical highlight `id`:s to the actual attributes.
 	`id` 0 will always be used for the default highlight with colors defined
 	by `default_colors_set` and no styles applied.
 
-	Note: `id`:s can be reused if Nvim's internal highlight table is full.
-	In this case, Nvim will always issue redraws of screen cells that are
-	affected by redefined `id`:s, so UIs do not need to keep track of this
+	Note: Nvim may reuse `id` values if its internal highlight table is full.
+	In that case Nvim will always issue redraws of screen cells that are
+	affected by redefined ids, so UIs do not need to keep track of this
 	themselves.
 
-	`info` is an empty array per default, and will be used by the
-	|ui-hlstate| extension explaned below.
+	`info` is an empty array by default, and will be used by the
+	|ui-hlstate| extension explained below.
 
 							    *ui-event-grid_line*
 ["grid_line", grid, row, col_start, cells]
-	Redraw a continous part of a `row` on a `grid`, starting at the column
+	Redraw a continuous part of a `row` on a `grid`, starting at the column
 	`col_start`. `cells` is an array of arrays each with 1 to 3 items:
 	`[text(, hl_id, repeat)]` . `text` is the UTF-8 text that should be put in
 	a cell, with the highlight `hl_id` defined by a previous `hl_attr_define`
@@ -407,7 +403,7 @@ option is not set. New UIs should use |ui-linegrid|.
 	updates. All boolean keys default to false.
 
 	`foreground`:	foreground color.
-	`background`:	backround color.
+	`background`:	background color.
 	`special`:	color to use for underline and undercurl, when present.
 	`reverse`:	reverse video. Foreground and background colors are
 			switched.
@@ -465,10 +461,10 @@ Detailed highlight state Extension 				  *ui-hlstate*
 Only sent if `ext_hlstate` option is set in |ui-options|. `ext_hlstate` implies
 `ext_linegrid`.
 
-By default, nvim will only describe grid cells using the final calculated
-higlight attributes, as described by the dict keys in |ui-event-highlight_set|.
+By default Nvim will only describe grid cells using the final calculated
+highlight attributes, as described by the dict keys in |ui-event-highlight_set|.
 The `ext_hlstate` extension allows to the UI to also receive a semantic
-describtion of the higlights active in a cell. In this mode highlights will be
+description of the highlights active in a cell. In this mode highlights will be
 predefined in a table, see |ui-event-hl_attr_define| and |ui-event-grid_line|.
 The `info` parameter in `hl_attr_define` will contain a semantic description
 of the highlights. As highlight groups can be combined, this will be an array
@@ -476,14 +472,13 @@ of items, with the item with highest priority last. Each item is a dictionary
 with the following possible keys:
 
     `kind`:	always present. One of the following values:
-	"ui":       A builtin ui highlight.
-	"syntax":   highlight applied to a buffer by a syntax declaration or
-	            other runtime/plugin functionallity such as
+	"ui":       Builtin UI highlight. |highlight-groups|
+	"syntax":   Highlight applied to a buffer by a syntax declaration or
+	            other runtime/plugin functionality such as
 		    |nvim_buf_add_highlight()|
 	"terminal": highlight from a process running in a |terminal-emulator|.
-		    Contains no futher semantic information.
-    `ui_name`:	Name of the builtin highlight. See |highlight-groups| for
-	        possible values. Only present for "ui".
+		    Contains no further semantic information.
+    `ui_name`:	Highlight name from |highlight-groups|. Only for "ui" kind.
     `hi_name`:	Name of the final |:highlight| group where the used
 		attributes are defined.
     `id`:	Unique numeric id representing this item.
@@ -532,7 +527,7 @@ tabs.
 
 ["win_external_pos", grid, win]
 	Display or reconfigure external window `win`. The window should be
-	displayed as a separate top-level window in the desktop envirionment,
+	displayed as a separate top-level window in the desktop environment,
 	or something similar.
 
 ["win_hide", grid]
diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py
index a62d18f02e..3449cf68e5 100755
--- a/scripts/gen_vimdoc.py
+++ b/scripts/gen_vimdoc.py
@@ -219,6 +219,14 @@ def doc_wrap(text, prefix='', width=70, func=False, indent=None):
     return result
 
 
+def has_nonexcluded_params(nodes):
+    """Returns true if any of the given <parameterlist> elements has at least
+    one non-excluded item."""
+    for n in nodes:
+        if render_params(n) != '':
+            return True
+
+
 def render_params(parent, width=62):
     """Renders Doxygen <parameterlist> tag as Vim help text."""
     name_length = 0
@@ -356,7 +364,7 @@ def render_para(parent, indent='', width=62):
 
     chunks = [text]
     # Generate text from the gathered items.
-    if len(groups['params']) > 0:
+    if len(groups['params']) > 0 and has_nonexcluded_params(groups['params']):
         chunks.append('\nParameters: ~')
         for child in groups['params']:
             chunks.append(render_params(child, width=width))
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index e27c85cd4f..da4db60ad6 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -97,7 +97,7 @@ String buffer_get_line(Buffer buffer, Integer index, Error *err)
   return rv;
 }
 
-/// Activate updates from this buffer to the current channel.
+/// Activates buffer-update events on the channel.
 ///
 /// @param channel_id
 /// @param buffer Buffer handle, or 0 for current buffer
@@ -106,7 +106,7 @@ String buffer_get_line(Buffer buffer, Integer index, Error *err)
 ///        `nvim_buf_lines_event`. Otherwise, the first notification will be
 ///        a `nvim_buf_changedtick_event`
 /// @param  opts  Optional parameters. Reserved for future use.
-/// @param[out] err Details of an error that may have occurred
+/// @param[out] err Error details, if any
 /// @return False when updates couldn't be enabled because the buffer isn't
 ///         loaded or `opts` contained an invalid key; otherwise True.
 Boolean nvim_buf_attach(uint64_t channel_id,
@@ -129,12 +129,12 @@ Boolean nvim_buf_attach(uint64_t channel_id,
 
   return buf_updates_register(buf, channel_id, send_buffer);
 }
-//
-/// Deactivate updates from this buffer to the current channel.
+
+/// Deactivates buffer-update events on the channel.
 ///
 /// @param channel_id
 /// @param buffer Buffer handle, or 0 for current buffer
-/// @param[out] err Details of an error that may have occurred
+/// @param[out] err Error details, if any
 /// @return False when updates couldn't be disabled because the buffer
 ///         isn't loaded; otherwise True.
 Boolean nvim_buf_detach(uint64_t channel_id,
diff --git a/src/nvim/api/ui.c b/src/nvim/api/ui.c
index d50a91f261..fd94418d48 100644
--- a/src/nvim/api/ui.c
+++ b/src/nvim/api/ui.c
@@ -76,6 +76,21 @@ void remote_ui_wait_for_attach(void)
                             pmap_has(uint64_t)(connected_uis, CHAN_STDIO));
 }
 
+/// Activates UI events on the channel.
+///
+/// Entry point of all UI clients.  Allows |\-\-embed| to continue startup.
+/// Implies that the client is ready to show the UI.  Adds the client to the
+/// list of UIs. |nvim_list_uis()|
+///
+/// @note If multiple UI clients are attached, the global screen dimensions
+///       degrade to the smallest client. E.g. if client A requests 80x40 but
+///       client B requests 200x100, the global screen has size 80x40.
+///
+/// @param channel_id
+/// @param width  Requested screen columns
+/// @param height  Requested screen rows
+/// @param options  |ui-options| map
+/// @param[out] err Error details, if any
 void nvim_ui_attach(uint64_t channel_id, Integer width, Integer height,
                     Dictionary options, Error *err)
   FUNC_API_SINCE(1) FUNC_API_REMOTE_ONLY
@@ -164,6 +179,12 @@ void ui_attach(uint64_t channel_id, Integer width, Integer height,
   api_free_dictionary(opts);
 }
 
+/// Deactivates UI events on the channel.
+///
+/// Removes the client from the list of UIs. |nvim_list_uis()|
+///
+/// @param channel_id
+/// @param[out] err Error details, if any
 void nvim_ui_detach(uint64_t channel_id, Error *err)
   FUNC_API_SINCE(1) FUNC_API_REMOTE_ONLY
 {