doc #10017

- gen_vimdoc.py: fancy "bullet"
- rework `:help channel-callback`
- rename `:help buffered` to `:help channel-buffered`

11 files changed, 150 insertions, 168 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index ed6e4905b4..3d95dd58f7 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -670,38 +670,39 @@ nvim_open_win({buffer}, {enter}, {config})                   *nvim_open_win()*
                               current window)
                     {config}  Dictionary for the window configuration accepts
                               these keys:
-                              -  `relative` : If set, the window becomes a floating
+                              •  `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
+                                • "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.
+                                  used by default.
+                                • "cursor" the cursor position in current
+                                  window.
 
-                              - `win` : When using relative='win', window id
+                              • `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
+                              •  `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
+                                • "NW" north-west (default)
+                                • "NE" north-east
+                                • "SW" south-west
+                                • "SE" south-east
 
-                              - `height` : window height (in character cells).
+                              • `height` : window height (in character cells).
                                 Minimum of 1.
-                              - `width` : window width (in character cells).
+                              • `width` : window width (in character cells).
                                 Minimum of 1.
-                              - `row` : row position. Screen cell height are
+                              • `row` : row position. Screen cell height are
                                 used as unit. Can be floating point.
-                              - `col` : column position. Screen cell width is
+                              • `col` : column position. Screen cell width is
                                 used as unit. Can be floating point.
-                              - `focusable` : Whether window can be focused by
+                              • `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
+                              • `external` : GUI should display the window as
                                 an external top-level window. Currently
                                 accepts no other positioning configuration
                                 together with this.
@@ -869,35 +870,43 @@ nvim_get_api_info()                                      *nvim_get_api_info()*
                                                       *nvim_set_client_info()*
 nvim_set_client_info({name}, {version}, {type}, {methods},
                      {attributes})
-                Identifies the client. Can be called more than once;
-                subsequent calls remove earlier info, which should be included
-                by the caller if it is still valid. (E.g. if a library first
-                identifies the channel, then a plugin using that library later
-                overrides that info)
+                Self-identifies the client.
+
+                The client/plugin/application should call this after
+                connecting, to provide hints about its identity and purpose,
+                for debugging and orchestration.
+
+                Can be called more than once; the caller should merge old info
+                if appropriate. Example: library first identifies the channel,
+                then a plugin using that library later identifies itself.
+
+                Note:
+                    "Something is better than nothing". You don't need to
+                    include all the fields.
 
                 Parameters: ~
                     {name}        Short name for the connected client
                     {version}     Dictionary describing the version, with
                                   these (optional) keys:
-                                  - "major" major version (defaults to 0 if
+                                  • "major" major version (defaults to 0 if
                                     not set, for no release yet)
-                                  - "minor" minor version
-                                  - "patch" patch number
-                                  - "prerelease" string describing a
+                                  • "minor" minor version
+                                  • "patch" patch number
+                                  • "prerelease" string describing a
                                     prerelease, like "dev" or "beta1"
-                                  - "commit" hash or similar identifier of
+                                  • "commit" hash or similar identifier of
                                     commit
                     {type}        Must be one of the following values. Client
                                   libraries should default to "remote" unless
                                   overridden by the user.
-                                  - "remote" remote client connected to Nvim.
-                                  - "ui" gui frontend
-                                  - "embedder" application using Nvim as a
+                                  • "remote" remote client connected to Nvim.
+                                  • "ui" gui frontend
+                                  • "embedder" application using Nvim as a
                                     component (for example, IDE/editor
                                     implementing a vim mode).
-                                  - "host" plugin host, typically started by
+                                  • "host" plugin host, typically started by
                                     nvim
-                                  - "plugin" single plugin, started by nvim
+                                  • "plugin" single plugin, started by nvim
                     {methods}     Builtin methods in the client. For a host,
                                   this does not include plugin methods which
                                   will be discovered later. The key should be
@@ -907,19 +916,19 @@ nvim_set_client_info({name}, {version}, {type}, {methods},
                                   unknown keys are ignored. Clients must only
                                   use keys defined in this or later versions
                                   of Nvim):
-                                  - "async" if true, send as a notification.
+                                  • "async" if true, send as a notification.
                                     If false or unspecified, use a blocking
                                     request
-                                  - "nargs" Number of arguments. Could be a
+                                  • "nargs" Number of arguments. Could be a
                                     single integer or an array of two
                                     integers, minimum and maximum inclusive.
                     {attributes}  Arbitrary string:string map of informal
                                   client properties. Suggested keys:
-                                  - "website": Client homepage URL (e.g.
+                                  • "website": Client homepage URL (e.g.
                                     GitHub repository)
-                                  - "license": License description ("Apache
+                                  • "license": License description ("Apache
                                     2", "GPLv3", "MIT", …)
-                                  - "logo": URI or path to image, preferably
+                                  • "logo": URI or path to image, preferably
                                     small logo or icon. .png or .svg format is
                                     preferred.
 
@@ -928,26 +937,26 @@ nvim_get_chan_info({chan})                              *nvim_get_chan_info()*
 
                 Return: ~
                     Dictionary describing a channel, with these keys:
-                    - "stream" the stream underlying the channel
-                      - "stdio" stdin and stdout of this Nvim instance
-                      - "stderr" stderr of this Nvim instance
-                      - "socket" TCP/IP socket or named pipe
-                      - "job" job with communication over its stdio
-
-                    - "mode" how data received on the channel is interpreted
-                      - "bytes" send and receive raw bytes
-                      - "terminal" a |terminal| instance interprets ASCII
+                    • "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 receive raw bytes
+                      • "terminal" a |terminal| instance interprets ASCII
                         sequences
-                      - "rpc" |RPC| communication on the channel is active
+                      • "rpc" |RPC| communication on the channel is active
 
-                    - "pty" Name of pseudoterminal, if one is used (optional).
+                    • "pty" Name of pseudoterminal, if one is used (optional).
                       On a POSIX system, this will be a device path like
                       /dev/pts/1. Even if the name is unknown, the key will
                       still be present to indicate a pty is used. This is
                       currently the case when using winpty on windows.
-                    - "buffer" buffer with connected |terminal| instance
+                    • "buffer" buffer with connected |terminal| instance
                       (optional)
-                    - "client" information about the client on the other end
+                    • "client" information about the client on the other end
                       of the RPC channel, if it has added it using
                       |nvim_set_client_info()|. (optional)
 
@@ -995,21 +1004,21 @@ nvim_parse_expression({expr}, {flags}, {highlight})
                     {expr}       Expression to parse. Always treated as a
                                  single line.
                     {flags}      Flags:
-                                 - "m" if multiple expressions in a row are
+                                 • "m" if multiple expressions in a row are
                                    allowed (only the first one will be
                                    parsed),
-                                 - "E" if EOC tokens are not allowed
+                                 • "E" if EOC tokens are not allowed
                                    (determines whether they will stop parsing
                                    process or be recognized as an
                                    operator/space, though also yielding an
                                    error).
-                                 - "l" when needing to start parsing with
+                                 • "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>=".
-                                 - empty string for ":call".
-                                 - "lm" to parse for ":let".
+                                 • "m" to parse like for ":echo".
+                                 • "E" to parse like for "<C-r>=".
+                                 • empty string for ":call".
+                                 • "lm" to parse for ":let".
                     {highlight}  If true, return value will also include
                                  "highlight" key containing array of 4-tuples
                                  (arrays) (Integer, Integer, Integer, String),
@@ -1021,64 +1030,64 @@ nvim_parse_expression({expr}, {flags}, {highlight})
 
                 Return: ~
 
-                    - AST: top-level dictionary with these keys:
-                      - "error": Dictionary with error, present only if parser
+                    • AST: top-level dictionary with these keys:
+                      • "error": Dictionary with error, present only if parser
                         saw some error. Contains the following keys:
-                        - "message": String, error message in printf format,
+                        • "message": String, error message in printf format,
                           translated. Must contain exactly one "%.*s".
-                        - "arg": String, error message argument.
+                        • "arg": String, error message argument.
 
-                      - "len": Amount of bytes successfully parsed. With flags
+                      • "len": Amount of bytes successfully parsed. With flags
                         equal to "" that should be equal to the length of expr
                         string. (“Sucessfully parsed” here means “participated
                         in AST creation”, not “till the first error”.)
-                      - "ast": AST, either nil or a dictionary with these
+                      • "ast": AST, either nil or a dictionary with these
                         keys:
-                        - "type": node type, one of the value names from
+                        • "type": node type, one of the value names from
                           ExprASTNodeType stringified without "kExprNode"
                           prefix.
-                        - "start": a pair [line, column] describing where node
+                        • "start": a pair [line, column] describing where node
                           is "started" where "line" is always 0 (will not be 0
                           if you will be using nvim_parse_viml() on e.g.
                           ":let", but that is not present yet). Both elements
                           are Integers.
-                        - "len": “length” of the node. This and "start" are
+                        • "len": “length” of the node. This and "start" are
                           there for debugging purposes primary (debugging
                           parser and providing debug information).
-                        - "children": a list of nodes described in top/"ast".
+                        • "children": a list of nodes described in top/"ast".
                           There always is zero, one or two children, key will
                           not be present if node has no children. Maximum
                           number of children may be found in node_maxchildren
                           array.
 
-                    - Local values (present only for certain nodes):
-                      - "scope": a single Integer, specifies scope for
+                    • Local values (present only for certain nodes):
+                      • "scope": a single Integer, specifies scope for
                         "Option" and "PlainIdentifier" nodes. For "Option" it
                         is one of ExprOptScope values, for "PlainIdentifier"
                         it is one of ExprVarScope values.
-                      - "ident": identifier (without scope, if any), present
+                      • "ident": identifier (without scope, if any), present
                         for "Option", "PlainIdentifier", "PlainKey" and
                         "Environment" nodes.
-                      - "name": Integer, register name (one character) or -1.
+                      • "name": Integer, register name (one character) or -1.
                         Only present for "Register" nodes.
-                      - "cmp_type": String, comparison type, one of the value
+                      • "cmp_type": String, comparison type, one of the value
                         names from ExprComparisonType, stringified without
                         "kExprCmp" prefix. Only present for "Comparison"
                         nodes.
-                      - "ccs_strategy": String, case comparison strategy, one
+                      • "ccs_strategy": String, case comparison strategy, one
                         of the value names from ExprCaseCompareStrategy,
                         stringified without "kCCStrategy" prefix. Only present
                         for "Comparison" nodes.
-                      - "augmentation": String, augmentation type for
+                      • "augmentation": String, augmentation type for
                         "Assignment" nodes. Is either an empty string, "Add",
                         "Subtract" or "Concat" for "=", "+=", "-=" or ".="
                         respectively.
-                      - "invert": Boolean, true if result of comparison needs
+                      • "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"
+                      • "ivalue": Integer, integer value for "Integer" nodes.
+                      • "fvalue": Float, floating-point value for "Float"
                         nodes.
-                      - "svalue": String, value for "SingleQuotedString" and
+                      • "svalue": String, value for "SingleQuotedString" and
                         "DoubleQuotedString" nodes.
 
 nvim__id({obj})                                                   *nvim__id()*
@@ -1140,12 +1149,12 @@ nvim_list_uis()                                              *nvim_list_uis()*
 
                 Return: ~
                     Array of UI dictionaries, each with these keys:
-                    - "height" Requested height of the UI
-                    - "width" Requested width of the UI
-                    - "rgb" true if the UI uses RGB colors (false implies
+                    • "height" Requested height of the UI
+                    • "width" Requested width of the UI
+                    • "rgb" true if the UI uses RGB colors (false implies
                       |cterm-colors|)
-                    - "ext_..." Requested UI extensions, see |ui-option|
-                    - "chan" Channel id of remote UI (not present for TUI)
+                    • "ext_..." Requested UI extensions, see |ui-option|
+                    • "chan" Channel id of remote UI (not present for TUI)
 
 nvim_get_proc_children({pid})                       *nvim_get_proc_children()*
                 Gets the immediate children of process `pid` .
diff --git a/runtime/doc/channel.txt b/runtime/doc/channel.txt
index be3efb371f..323d9ef004 100644
--- a/runtime/doc/channel.txt
+++ b/runtime/doc/channel.txt
@@ -47,27 +47,23 @@ By default, channels opened by vimscript functions will operate with raw
 bytes. Additionally, for a job channel using rpc, bytes can still be
 read over its stderr. Similarily, only bytes can be written to nvim's own stderr.
 
-						    *channel-callback* *buffered*
-				*E5210* *on_stdout* *on_stderr* *on_stdin* *on_data*
-It is possible to register callback functions when a channel receives data by
-passing the `on_stdout`, `on_stderr`, `on_stdin` options on creation. Sockets
-may specify an `on_data` callback instead. Each callback function will be
-invoked with data read from the channel. By default, the callback will be
-invoked immediately when data is available, to facilitate interactive
-communication. The same callback will then be invoked with empty data, to
-indicate that the stream reached EOF. Alternatively the `stdout_buffered`,
-`stderr_buffered`, `stdin_buffered`, `data_buffered` options can be set to
-invoke the corresponding callback only when the underlying stream reaches EOF.
-The callback will then be passed complete output. This is helpful when only
-the complete output is useful, and not partial data. Futhermore if the stream
-is set to be buffered, but the callback is not set, the data is saved in the
-options dict, with the stream name as key. For this to work a new options dict
-must be used for each opened channel. If a script uses a global `s:job_opts`
-dict, it can be copied with |copy()| before supplying it to |jobstart()|. If a
-dict is reused, so that the dict key already is occupied, error `E5210` will
-be raised.
-
-- The arguments passed to the callback function are:
+			*channel-callback* *on_stdout* *on_stderr* *on_stdin* *on_data*
+Scripts can react to channel activity (received data) via callback functions
+assigned to the `on_stdout`, `on_stderr`, `on_stdin`, and `on_data` options.
+Callbacks should be fast, avoid potentially slow/expensive work.
+
+						*channel-buffered*
+By default the callback is invoked immediately as data is available; empty
+data indicates EOF (stream closed).  Alternatively, set the `stdout_buffered`,
+`stderr_buffered`, `stdin_buffered`, or `data_buffered` options to invoke the
+callback only on EOF, after all output was gathered.
+						*E5210*
+If the stream is set as buffered without assigning a callback, the data is
+saved in the options dict with the stream name as key. This requires a new
+options dict for each opened channel (|copy()|). If the stream name key
+is already set, error E5210 is raised.
+
+Channel callback functions accept these arguments:
 
   0: |channel-id|
   1: Raw data read from the channel, formatted as a |readfile()|-style
diff --git a/runtime/doc/cmdline.txt b/runtime/doc/cmdline.txt
index 81b0e17322..a3b5f6b22a 100644
--- a/runtime/doc/cmdline.txt
+++ b/runtime/doc/cmdline.txt
@@ -1099,8 +1099,8 @@ in the command-line window, like this: >
 Note that hitting <Tab> in Normal mode will do completion on the next
 character.  That way it works at the end of the line.
 If you don't want these mappings, disable them with: >
-	au CmdwinEnter [:>] iunmap <Tab>
-	au CmdwinEnter [:>] nunmap <Tab>
+	au CmdwinEnter [:>] iunmap <buffer> <Tab>
+	au CmdwinEnter [:>] nunmap <buffer> <Tab>
 You could put these lines in your vimrc file.
 
 While in the command-line window you cannot use the mouse to put the cursor in
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index b88138aea3..7682a1a584 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -10789,44 +10789,7 @@ code can be used: >
     unlet scriptnames_output
 
 ==============================================================================
-10. No +eval feature				*no-eval-feature*
-
-When the |+eval| feature was disabled at compile time, none of the expression
-evaluation commands are available.  To prevent this from causing Vim scripts
-to generate all kinds of errors, the ":if" and ":endif" commands are still
-recognized, though the argument of the ":if" and everything between the ":if"
-and the matching ":endif" is ignored.  Nesting of ":if" blocks is allowed, but
-only if the commands are at the start of the line.  The ":else" command is not
-recognized.
-
-Example of how to avoid executing commands when the |+eval| feature is
-missing: >
-
-	:if 1
-	:  echo "Expression evaluation is compiled in"
-	:else
-	:  echo "You will _never_ see this message"
-	:endif
-
-To execute a command only when the |+eval| feature is disabled requires a trick,
-as this example shows: >
-
-	silent! while 0
-	  set history=111
-	silent! endwhile
-
-When the |+eval| feature is available the command is skipped because of the
-"while 0".  Without the |+eval| feature the "while 0" is an error, which is
-silently ignored, and the command is executed.
-
-The "<CR>" here is a real CR character, type CTRL-V Enter to get it.
-
-When the |+eval| feature is available the ":" is remapped to add a double
-quote, which has the effect of commenting-out the command.  Without the
-|+eval| feature the nnoremap command is skipped and the command is executed.
-
-==============================================================================
-11. The sandbox					*eval-sandbox* *sandbox* *E48*
+The sandbox					*eval-sandbox* *sandbox* *E48*
 
 The 'foldexpr', 'formatexpr', 'includeexpr', 'indentexpr', 'statusline' and
 'foldtext' options may be evaluated in a sandbox.  This means that you are
@@ -10865,7 +10828,7 @@ Note that when in the sandbox and saving an option value and restoring it, the
 option will still be marked as it was set in the sandbox.
 
 ==============================================================================
-12. Textlock							*textlock*
+Textlock							*textlock*
 
 In a few situations it is not allowed to change the text in the buffer, jump
 to another window and some other things that might confuse or break what Vim
@@ -10881,7 +10844,7 @@ This is not allowed when the textlock is active:
 	- etc.
 
 ==============================================================================
-13. Command-line expressions highlighting		*expr-highlight*
+Command-line expressions highlighting		*expr-highlight*
 
 Expressions entered by the user in |i_CTRL-R_=|, |c_CTRL-\_e|, |quote=| are
 highlighted by the built-in expressions parser.  It uses highlight groups
diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt
index e2d1f0f675..92c25ba875 100644
--- a/runtime/doc/if_lua.txt
+++ b/runtime/doc/if_lua.txt
@@ -491,9 +491,9 @@ tbl_extend({behavior}, {...})                               *vim.tbl_extend()*
                 Parameters: ~
                     {behavior}  Decides what to do if a key is found in more
                                 than one map:
-                                - "error": raise an error
-                                - "keep": use value from the leftmost map
-                                - "force": use value from the rightmost map
+                                • "error": raise an error
+                                • "keep": use value from the leftmost map
+                                • "force": use value from the rightmost map
                     {...}       Two or more map-like tables.
 
                 See also: ~
@@ -510,7 +510,7 @@ tbl_flatten({t})                                           *vim.tbl_flatten()*
                     Flattened copy of the given list-like table.
 
 trim({s})                                                         *vim.trim()*
-                Trim whitespace (Lua pattern "%%s") from both sides of a
+                Trim whitespace (Lua pattern "%s") from both sides of a
                 string.
 
                 Parameters: ~
diff --git a/runtime/doc/msgpack_rpc.txt b/runtime/doc/msgpack_rpc.txt
index 91a4a3c267..b24e706aa9 100644
--- a/runtime/doc/msgpack_rpc.txt
+++ b/runtime/doc/msgpack_rpc.txt
@@ -51,7 +51,7 @@ There are three ways to obtain API metadata:
   3. Use the |api_info()| vimscript function.
 
 To get a human-readable list of API functions: >
-    :new|put =map(api_info().functions, 'v:val.name')
+    :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name')
 <
 To get a formatted dump of the API using python (requires the `pyyaml` and
 `msgpack-python` packages): >
diff --git a/runtime/doc/various.txt b/runtime/doc/various.txt
index a0b2846b2b..2b6afcbdbc 100644
--- a/runtime/doc/various.txt
+++ b/runtime/doc/various.txt
@@ -470,17 +470,18 @@ gO			Show a filetype-specific, navigable "outline" of the
 			Currently works in |help| and |:Man| buffers.
 
 [N]gs							*gs* *:sl* *:sleep*
-:[N]sl[eep] [N]	[m]	Do nothing for [N] seconds.  When [m] is included,
-			sleep for [N] milliseconds.  The count for "gs" always
-			uses seconds.  The default is one second. >
+:[N]sl[eep] [N]	[m]	Do nothing for [N] seconds, or [N] milliseconds if [m]
+			was given.  "gs" always uses seconds.
+			Default is one second. >
 			     :sleep	     "sleep for one second
 			     :5sleep	     "sleep for five seconds
 			     :sleep 100m     "sleep for a hundred milliseconds
 			     10gs	     "sleep for ten seconds
-<			Can be interrupted with CTRL-C (CTRL-Break on Windows).
+<			Can be interrupted with CTRL-C.
 			"gs" stands for "goto sleep".
 			While sleeping the cursor is positioned in the text,
 			if at a visible position.
+			Queued messages are processed during the sleep.
 
 ==============================================================================
 2. Using Vim like less or more					*less*
diff --git a/runtime/lua/vim/shared.lua b/runtime/lua/vim/shared.lua
index 1038a95dd3..75d4a6eee6 100644
--- a/runtime/lua/vim/shared.lua
+++ b/runtime/lua/vim/shared.lua
@@ -168,7 +168,7 @@ local function tbl_flatten(t)
   return result
 end
 
---- Trim whitespace (Lua pattern "%%s") from both sides of a string.
+--- Trim whitespace (Lua pattern "%s") from both sides of a string.
 ---
 --@see https://www.lua.org/pil/20.2.html
 --@param s String to trim
diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py
index e491ff59b0..8db5d4de5b 100755
--- a/scripts/gen_vimdoc.py
+++ b/scripts/gen_vimdoc.py
@@ -325,7 +325,7 @@ def render_node(n, text, prefix='', indent='', width=62):
             text = doc_wrap(text, indent=indent, width=width)
     elif n.nodeName == 'itemizedlist':
         for c in n.childNodes:
-            text += '{}\n'.format(render_node(c, text, prefix='- ',
+            text += '{}\n'.format(render_node(c, text, prefix='• ',
                 indent=indent, width=width))
     elif n.nodeName == 'orderedlist':
         i = 1
diff --git a/scripts/lua2dox.lua b/scripts/lua2dox.lua
index ae76a36d50..77cdabcc4b 100644
--- a/scripts/lua2dox.lua
+++ b/scripts/lua2dox.lua
@@ -478,12 +478,14 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename)
     outStream:writelnTail('// #######################')
     outStream:writelnTail()
 
+    local state = ''
     while not (err or inStream:eof()) do
       line = string_trim(inStream:getLine())
       -- 			TCore_Debug_show_var('inStream',inStream)
       -- 			TCore_Debug_show_var('line',line )
-      if string.sub(line,1,2)=='--' then -- its a comment
+      if string.sub(line,1,2)=='--' then -- it's a comment
         if string.sub(line,3,3)=='@' then -- it's a magic comment
+          state = 'in_magic_comment'
           local magic = string.sub(line,4)
           outStream:writeln('/// @' .. magic)
           fn_magic = checkComment4fn(fn_magic,magic)
@@ -517,12 +519,16 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename)
             outStream:write('/* zz:' .. comment .. '*/  ')
             fn_magic = nil
           end
-        else
+        -- TODO(justinmk): Uncomment this if we want "--" lines to continue the
+        --                 preceding magic ("---", "--@", …) lines.
+        -- elseif state == 'in_magic_comment' then  -- next line of magic comment
+        --   outStream:writeln('/// '.. line:sub(3))
+        else -- discard
           outStream:writeln('// zz:"' .. line .. '"')
           fn_magic = nil
         end
       elseif string.find(line,'^function') or string.find(line,'^local%s+function') then
-        -- it's a function
+        state = 'in_function'  -- it's a function
         local pos_fn = string.find(line,'function')
         -- function
         -- ....v...
@@ -578,7 +584,7 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename)
         end
         fn_magic = nil -- mustn't indavertently use it again
       elseif string.find(line,'=%s*class%(') then
-        -- it's a class declaration
+        state = 'in_class'  -- it's a class declaration
         local tailComment
         line,tailComment = TString_removeCommentFromLine(line)
         local equals = string.find(line,'=')
@@ -592,8 +598,8 @@ function TLua2DoX_filter.readfile(this,AppStamp,Filename)
         end
         outStream:writeln('class ' .. klass .. parent .. '{};')
       else
-        -- we don't know what this line means, so we can probably just comment it out
-        if #line>0 then
+        state = ''  -- unknown
+        if #line>0 then  -- we don't know what this line means, so just comment it out
           outStream:writeln('// zz: ' .. line)
         else
           outStream:writeln() -- keep this line blank
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index b8c863704a..9b5e0fc40b 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -1027,7 +1027,7 @@ Buffer nvim_create_buf(Boolean listed, Boolean scratch, Error *err)
 ///      - "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.
+///      - "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:
@@ -1336,10 +1336,17 @@ Array nvim_get_api_info(uint64_t channel_id)
   return rv;
 }
 
-/// Identifies the client. Can be called more than once; subsequent calls
-/// remove earlier info, which should be included by the caller if it is
-/// still valid. (E.g. if a library first identifies the channel, then a
-/// plugin using that library later overrides that info)
+/// Self-identifies the client.
+///
+/// The client/plugin/application should call this after connecting, to provide
+/// hints about its identity and purpose, for debugging and orchestration.
+///
+/// Can be called more than once; the caller should merge old info if
+/// appropriate. Example: library first identifies the channel, then a plugin
+/// using that library later identifies itself.
+///
+/// @note "Something is better than nothing". You don't need to include all the
+///       fields.
 ///
 /// @param channel_id
 /// @param name Short name for the connected client