diff options
| -rw-r--r-- | runtime/doc/api.txt | 175 | ||||
| -rw-r--r-- | runtime/doc/channel.txt | 38 | ||||
| -rw-r--r-- | runtime/doc/cmdline.txt | 4 | ||||
| -rw-r--r-- | runtime/doc/eval.txt | 43 | ||||
| -rw-r--r-- | runtime/doc/if_lua.txt | 8 | ||||
| -rw-r--r-- | runtime/doc/msgpack_rpc.txt | 2 | ||||
| -rw-r--r-- | runtime/doc/various.txt | 9 | ||||
| -rw-r--r-- | runtime/lua/vim/shared.lua | 2 | ||||
| -rwxr-xr-x | scripts/gen_vimdoc.py | 2 | ||||
| -rw-r--r-- | scripts/lua2dox.lua | 18 | ||||
| -rw-r--r-- | src/nvim/api/vim.c | 17 |
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 |