doc: UI

5 files changed, 105 insertions, 71 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 6b80b71335..8ef058fbb8 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -1159,7 +1159,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
@@ -1178,7 +1178,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
@@ -1736,10 +1736,29 @@ 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()|
+
+                Parameters: ~
 
 nvim_ui_try_resize({width}, {height})                   *nvim_ui_try_resize()*
                 TODO: Documentation
diff --git a/runtime/doc/starting.txt b/runtime/doc/starting.txt
index a8ba64fda8..d148e1d8cd 100644
--- a/runtime/doc/starting.txt
+++ b/runtime/doc/starting.txt
@@ -355,35 +355,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 3d14f83ae5..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*
@@ -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.
@@ -531,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/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
 {