diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index d72b6d3d20..834dcabcba 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -1438,26 +1438,26 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) field of |nvim_get_chan_info()|. • {version} (`table`) Dict describing the version, with these (optional) keys: + • "commit" hash or similar identifier of commit • "major" major version (defaults to 0 if not set, for no release yet) • "minor" minor version • "patch" patch number • "prerelease" string describing a prerelease, like "dev" or "beta1" - • "commit" hash or similar identifier of commit • {type} (`string`) Must be one of the following values. Client libraries should default to "remote" unless overridden by the user. - • "remote" remote client connected "Nvim flavored" - MessagePack-RPC (responses must be in reverse order of - requests). |msgpack-rpc| - • "msgpack-rpc" remote client connected to Nvim via - fully MessagePack-RPC compliant protocol. - • "ui" gui frontend • "embedder" application using Nvim as a component (for example, IDE/editor implementing a vim mode). • "host" plugin host, typically started by nvim + • "msgpack-rpc" remote client connected to Nvim via + fully MessagePack-RPC compliant protocol. • "plugin" single plugin, started by nvim + • "remote" remote client connected "Nvim flavored" + MessagePack-RPC (responses must be in reverse order of + requests). |msgpack-rpc| + • "ui" gui frontend • {methods} (`table`) Builtin methods in the client. For a host, this does not include plugin methods which will be discovered later. The key should be the method name, @@ -1472,13 +1472,13 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes}) inclusive. • {attributes} (`table`) Arbitrary string:string map of informal client properties. Suggested keys: - • "pid": Process id. - • "website": Client homepage URL (e.g. GitHub - repository) • "license": License description ("Apache 2", "GPLv3", "MIT", …) • "logo": URI or path to image, preferably small logo or icon. .png or .svg format is preferred. + • "pid": Process id. + • "website": Client homepage URL (e.g. GitHub + repository) nvim_set_current_buf({buf}) *nvim_set_current_buf()* Sets the current window's buffer to `buf`. @@ -1651,9 +1651,9 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {opts}) *nvim_set_keymap()* • {opts} (`vim.api.keyset.keymap`) Optional parameters map: Accepts all |:map-arguments| as keys except , values are booleans (default false). Also: - • "noremap" disables |recursive_mapping|, like |:noremap| - • "desc" human-readable description. • "callback" Lua function called in place of {rhs}. + • "desc" human-readable description. + • "noremap" disables |recursive_mapping|, like |:noremap| • "replace_keycodes" (boolean) When "expr" is true, replace keycodes in the resulting string (see |nvim_replace_termcodes()|). Returning nil from the Lua @@ -1984,17 +1984,18 @@ nvim_parse_expression({expr}, {flags}, {hl}) *nvim_parse_expression()* • {expr} (`string`) Expression to parse. Always treated as a single line. • {flags} (`string`) Flags: - • "m" if multiple expressions in a row are allowed (only the - first one will be parsed), • "E" if EOC tokens are not allowed (determines whether they will stop parsing process or be recognized as an operator/space, though also yielding an error). • "l" when needing to start parsing with lvalues for ":let" - or ":for". Common flag sets: - • "m" to parse like for `":echo"`. - • "E" to parse like for `"="`. - • empty string for ":call". - • "lm" to parse for ":let". + or ":for". + • "m" if multiple expressions in a row are allowed (only the + first one will be parsed), + • Common flag sets: + • "E" to parse like for `"="`. + • "lm" to parse for ":let". + • "m" to parse like for `":echo"`. + • empty string for ":call". • {hl} (`boolean`) If true, return value will also include "highlight" key containing array of 4-tuples (arrays) (Integer, Integer, Integer, String), where first three @@ -2144,15 +2145,15 @@ nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()* triggered. Lua callback can return |lua-truthy| to delete the autocommand. Callback receives one argument, a table with keys: *event-args* - • id: (`number`) Autocommand id - • event: (`vim.api.keyset.events`) Name of the triggered - event |autocmd-events| - • group: (`number?`) Group id, if any - • file: (`string`) (not expanded to a full path) - • match: (`string`) (expanded to a full path) • buf: (`number`) • data: (`any`) Arbitrary data passed from |nvim_exec_autocmds()| *event-data* + • event: (`vim.api.keyset.events`) Name of the triggered + event |autocmd-events| + • file: (`string`) (not expanded to a full path) + • group: (`number?`) Group id, if any + • id: (`number`) Autocommand id + • match: (`string`) (expanded to a full path) • command (string?) Vim command executed on event. Not allowed with {callback}. • desc (`string?`) Description (for documentation and @@ -2927,45 +2928,43 @@ nvim_create_user_command({name}, {cmd}, {opts}) Since: 0.7.0 Parameters: ~ - • {name} (`string`) Name of the new user command. Must begin with an - uppercase letter. + • {name} (`string`) Command name. First char must be uppercase. • {cmd} (`string|fun(args: vim.api.keyset.create_user_command.command_args)`) - Replacement command to execute when this user command is - executed. When called from Lua, the command can also be a Lua - function. The function is called with a single table argument - that contains the following keys: - • args: (string) The args passed to the command, if any - • bang: (boolean) "true" if the command was executed with a ! - modifier - • count: (number) Any count supplied - • fargs: (table) The args split by unescaped whitespace (when - more than one argument is allowed), if any - • line1: (number) The starting line of the command range - - • line2: (number) The final line of the command range - • mods: (string) Command modifiers, if any - • name: (string) Command name - • nargs: (string) Number of arguments allowed for the command - • range: (number) The number of items in the command range: 0, - 1, or 2 - • reg: (string) The optional register, if specified - • smods: (table) Command modifiers in a structured format. Has - the same structure as the "mods" key of |nvim_parse_cmd()|. - • {opts} (`vim.api.keyset.user_command`) Optional flags - • `desc` (string) Command description. - • `force` (boolean, default true) Override any previous - definition. - • `complete` |:command-complete| command or function like - |:command-completion-customlist|. - • `nargs` Number of arguments allowed for the command + Command or Lua function, executed when the command is invoked. + Lua function receives a table with keys: + • args: (string) Args passed to the command, if any. + • bang: (boolean) true if the command was executed with "!". + + • count: (number) Count, if any. + • fargs: (table) Args split by unescaped whitespace (when more + than one arg is allowed), if any. + • line1: (number) Start of the command range. + • line2: (number) End of the command range. + • mods: (string) Command modifiers (unstructured string), if + any. + • name: (string) Command name. + • nargs: (string) Number of arguments allowed by the command. |:command-nargs| - • `preview` (function) Preview handler for 'inccommand' + • range: (number) Number of items in the command range: 0, 1, + or 2. + • reg: (string) Register name, if any. + • smods: (table) Command modifiers (structured), same as + "mods" in |nvim_parse_cmd()|. + • {opts} (`vim.api.keyset.user_command`) Optional flags: + • `addr` |:command-addr| + • `complete` |:command-complete| command or function + |:command-completion-customlist|. + • `count` |:command-count| + • `desc` (string) Command description. + • `force` (boolean, default true) Override the existing + definition, if any. + • `nargs` Number of arguments allowed by the command. + |:command-nargs| + • `preview` (function) Preview handler for 'inccommand'. |:command-preview| - • `range` see |:command-range| - • `count` see |:command-count| - • `addr` see |:command-addr| - • Set boolean |command-attributes| such as |:command-bang| or - |:command-bar| to true (but not |:command-buffer|, use + • `range` |:command-range| + • boolean |command-attributes| such as |:command-bang| or + |:command-bar| (but not |:command-buffer|, use |nvim_buf_create_user_command()| instead). nvim_del_user_command({name}) *nvim_del_user_command()* diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 02c718494a..b7992336cd 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -1151,7 +1151,7 @@ TabClosed After closing a tabpage. expands to the closing |tabpage-number|. *TabClosedPre* -TabClosedPre Before closing a tabpage. The current tabpage +TabClosedPre Before closing a tabpage. The current tabpage (|tabpagenr()|) is the one being closed. The window layout is locked, thus opening and closing of windows is prohibited. diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index f04ae649e8..4387629641 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -2074,10 +2074,10 @@ Client:stop({force}) *Client:stop()* Parameters: ~ • {force} (`integer|boolean?`) (default: `self.exit_timeout`) Decides whether to force-stop the server. + • `false`: Do not force-stop after "shutdown" request. • `nil`: Defaults to `exit_timeout` from |vim.lsp.ClientConfig|. • `true`: Force-stop after "shutdown" request. - • `false`: Do not force-stop after "shutdown" request. • number: Wait up to `force` milliseconds before force-stop. Client:supports_method({method}, {bufnr}) *Client:supports_method()* diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 2196d256d7..8a09a09332 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -2108,8 +2108,8 @@ vim.tbl_deep_extend({behavior}, {...}) *vim.tbl_deep_extend()* • {behavior} (`'error'|'keep'|'force'|fun(key:any, prev_value:any?, value:any): any`) 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 + • "keep": use value from the leftmost map • If a function, it receives the current key, the previous value in the currently merged table (if present), the current value and should return the value for the given @@ -2129,8 +2129,8 @@ vim.tbl_extend({behavior}, {...}) *vim.tbl_extend()* • {behavior} (`'error'|'keep'|'force'|fun(key:any, prev_value:any?, value:any): any`) 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 + • "keep": use value from the leftmost map • If a function, it receives the current key, the previous value in the currently merged table (if present), the current value and should return the value for the given diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index fca2cee2ef..acea182cd8 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -241,7 +241,7 @@ VIMSCRIPT • |v:exitreason| is set before |QuitPre|. • |v:starttime| is the process start time (nanoseconds since UNIX epoch). -• |v:useractive| timestamp of the most recent user activity. +• |v:useractive| indicates user activity. • |serverlist()| with `info=true` returns details for each server (own + peers). ============================================================================== diff --git a/runtime/doc/vvars.txt b/runtime/doc/vvars.txt index 50036044fc..b89818d26f 100644 --- a/runtime/doc/vvars.txt +++ b/runtime/doc/vvars.txt @@ -756,9 +756,10 @@ v:true *v:useractive* *useractive-variable* v:useractive - Timestamp indicating the most recent user activity. - Updated every time a key is received from a UI - (TUI keystrokes or RPC |nvim_input()|). + Timestamp (nanoseconds since UNIX epoch) indicating the most + recent user activity, i.e. when a key is received from a UI + (TUI input or |nvim_input()|). + Initialized to 0 (no user activity since startup). Read-only. diff --git a/runtime/lua/vim/_core/shared.lua b/runtime/lua/vim/_core/shared.lua index 77cfac2d9d..a67e8513a1 100644 --- a/runtime/lua/vim/_core/shared.lua +++ b/runtime/lua/vim/_core/shared.lua @@ -660,8 +660,8 @@ end --- ---@param behavior 'error'|'keep'|'force'|fun(key:any, prev_value:any?, value:any): any 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 +--- - "keep": use value from the leftmost map --- - If a function, it receives the current key, the previous value in the currently merged table (if present), the current value and should --- return the value for the given key in the merged table. ---@param ... table Two or more tables @@ -693,8 +693,8 @@ end ---@generic T2: table ---@param behavior 'error'|'keep'|'force'|fun(key:any, prev_value:any?, value:any): any 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 +--- - "keep": use value from the leftmost map --- - If a function, it receives the current key, the previous value in the currently merged table (if present), the current value and should --- return the value for the given key in the merged table. ---@param ... T2 Two or more tables diff --git a/runtime/lua/vim/_meta/api.gen.lua b/runtime/lua/vim/_meta/api.gen.lua index 8a1777cb78..11d1a58242 100644 --- a/runtime/lua/vim/_meta/api.gen.lua +++ b/runtime/lua/vim/_meta/api.gen.lua @@ -982,13 +982,13 @@ function vim.api.nvim_create_augroup(name, opts) end --- - callback (`function|string?`) Lua function (or Vimscript function name, if string) --- called when the event(s) is triggered. Lua callback can return `lua-truthy` to delete --- the autocommand. Callback receives one argument, a table with keys: [event-args]() ---- - id: (`number`) Autocommand id ---- - event: (`vim.api.keyset.events`) Name of the triggered event `autocmd-events` ---- - group: (`number?`) Group id, if any ---- - file: (`string`) [] (not expanded to a full path) ---- - match: (`string`) [] (expanded to a full path) --- - buf: (`number`) [] --- - data: (`any`) Arbitrary data passed from [nvim_exec_autocmds()] [event-data]() +--- - event: (`vim.api.keyset.events`) Name of the triggered event `autocmd-events` +--- - file: (`string`) [] (not expanded to a full path) +--- - group: (`number?`) Group id, if any +--- - id: (`number`) Autocommand id +--- - match: (`string`) [] (expanded to a full path) --- - command (string?) Vim command executed on event. Not allowed with {callback}. --- - desc (`string?`) Description (for documentation and troubleshooting). --- - group (`string|integer?`) Group name or id to match against. @@ -1033,35 +1033,33 @@ function vim.api.nvim_create_namespace(name) end --- Hello world! --- ``` --- ---- @param name string Name of the new user command. Must begin with an uppercase letter. ---- @param cmd string|fun(args: vim.api.keyset.create_user_command.command_args) Replacement command to execute when this user command is executed. When called ---- from Lua, the command can also be a Lua function. The function is called with a ---- single table argument that contains the following keys: ---- - args: (string) The args passed to the command, if any [] ---- - bang: (boolean) "true" if the command was executed with a ! modifier [] ---- - count: (number) Any count supplied [] ---- - fargs: (table) The args split by unescaped whitespace (when more than one ---- argument is allowed), if any [] ---- - line1: (number) The starting line of the command range [] ---- - line2: (number) The final line of the command range [] ---- - mods: (string) Command modifiers, if any [] ---- - name: (string) Command name ---- - nargs: (string) Number of arguments allowed for the command ---- - range: (number) The number of items in the command range: 0, 1, or 2 [] ---- - reg: (string) The optional register, if specified [] ---- - smods: (table) Command modifiers in a structured format. Has the same ---- structure as the "mods" key of `nvim_parse_cmd()`. ---- @param opts vim.api.keyset.user_command Optional flags +--- @param name string Command name. First char must be uppercase. +--- @param cmd string|fun(args: vim.api.keyset.create_user_command.command_args) Command or Lua function, executed when the command is invoked. Lua function +--- receives a table with keys: +--- - args: (string) Args passed to the command, if any. [] +--- - bang: (boolean) true if the command was executed with "!". [] +--- - count: (number) Count, if any. [] +--- - fargs: (table) Args split by unescaped whitespace (when more than one arg is +--- allowed), if any. [] +--- - line1: (number) Start of the command range. [] +--- - line2: (number) End of the command range. [] +--- - mods: (string) Command modifiers (unstructured string), if any. [] +--- - name: (string) Command name. +--- - nargs: (string) Number of arguments allowed by the command. `:command-nargs` +--- - range: (number) Number of items in the command range: 0, 1, or 2. [] +--- - reg: (string) Register name, if any. [] +--- - smods: (table) Command modifiers (structured), same as "mods" in `nvim_parse_cmd()`. +--- @param opts vim.api.keyset.user_command Optional flags: +--- - `addr` `:command-addr` +--- - `complete` `:command-complete` command or function `:command-completion-customlist`. +--- - `count` `:command-count` --- - `desc` (string) Command description. ---- - `force` (boolean, default true) Override any previous definition. ---- - `complete` `:command-complete` command or function like `:command-completion-customlist`. ---- - `nargs` Number of arguments allowed for the command `:command-nargs` ---- - `preview` (function) Preview handler for 'inccommand' `:command-preview` ---- - `range` see `:command-range` ---- - `count` see `:command-count` ---- - `addr` see `:command-addr` ---- - Set boolean `command-attributes` such as `:command-bang` or `:command-bar` to ---- true (but not `:command-buffer`, use `nvim_buf_create_user_command()` instead). +--- - `force` (boolean, default true) Override the existing definition, if any. +--- - `nargs` Number of arguments allowed by the command. `:command-nargs` +--- - `preview` (function) Preview handler for 'inccommand'. `:command-preview` +--- - `range` `:command-range` +--- - boolean `command-attributes` such as `:command-bang` or `:command-bar` (but +--- not `:command-buffer`, use `nvim_buf_create_user_command()` instead). function vim.api.nvim_create_user_command(name, cmd, opts) end --- Delete an autocommand group by id. @@ -1965,18 +1963,18 @@ function vim.api.nvim_parse_cmd(str, opts) end --- --- @param expr string Expression to parse. Always treated as a single line. --- @param flags string Flags: ---- - "m" if multiple expressions in a row are allowed (only ---- the first one will be parsed), --- - "E" if EOC tokens are not allowed (determines whether --- they will stop parsing process or be recognized as an --- operator/space, though also yielding an error). --- - "l" when needing to start parsing with lvalues for --- ":let" or ":for". ---- Common flag sets: ---- - "m" to parse like for `":echo"`. ---- - "E" to parse like for `"="`. ---- - empty string for ":call". ---- - "lm" to parse for ":let". +--- - "m" if multiple expressions in a row are allowed (only +--- the first one will be parsed), +--- - Common flag sets: +--- - "E" to parse like for `"="`. +--- - "lm" to parse for ":let". +--- - "m" to parse like for `":echo"`. +--- - empty string for ":call". --- @param hl boolean If true, return value will also include "highlight" --- key containing array of 4-tuples (arrays) (Integer, --- Integer, Integer, String), where first three numbers @@ -2305,9 +2303,9 @@ function vim.api.nvim_set_hl_ns_fast(ns_id) end --- @param rhs string Right-hand-side `{rhs}` of the mapping. --- @param opts vim.api.keyset.keymap Optional parameters map: Accepts all `:map-arguments` as keys except [], --- values are booleans (default false). Also: ---- - "noremap" disables `recursive_mapping`, like `:noremap` ---- - "desc" human-readable description. --- - "callback" Lua function called in place of {rhs}. +--- - "desc" human-readable description. +--- - "noremap" disables `recursive_mapping`, like `:noremap` --- - "replace_keycodes" (boolean) When "expr" is true, replace keycodes in the --- resulting string (see `nvim_replace_termcodes()`). Returning nil from the Lua --- "callback" is equivalent to returning an empty string. diff --git a/runtime/lua/vim/_meta/vvars.gen.lua b/runtime/lua/vim/_meta/vvars.gen.lua index 3f90cdecdd..28ced461bc 100644 --- a/runtime/lua/vim/_meta/vvars.gen.lua +++ b/runtime/lua/vim/_meta/vvars.gen.lua @@ -805,9 +805,10 @@ vim.v.throwpoint = ... --- @type boolean vim.v['true'] = ... ---- Timestamp indicating the most recent user activity. ---- Updated every time a key is received from a UI ---- (TUI keystrokes or RPC `nvim_input()`). +--- Timestamp (nanoseconds since UNIX epoch) indicating the most +--- recent user activity, i.e. when a key is received from a UI +--- (TUI input or `nvim_input()`). +--- --- Initialized to 0 (no user activity since startup). --- Read-only. --- @type integer diff --git a/runtime/lua/vim/lsp/client.lua b/runtime/lua/vim/lsp/client.lua index 3df6a03174..1173edb773 100644 --- a/runtime/lua/vim/lsp/client.lua +++ b/runtime/lua/vim/lsp/client.lua @@ -892,9 +892,9 @@ end --- file corruption. --- --- @param force? integer|boolean (default: `self.exit_timeout`) Decides whether to force-stop the server. +--- - `false`: Do not force-stop after "shutdown" request. --- - `nil`: Defaults to `exit_timeout` from |vim.lsp.ClientConfig|. --- - `true`: Force-stop after "shutdown" request. ---- - `false`: Do not force-stop after "shutdown" request. --- - number: Wait up to `force` milliseconds before force-stop. function Client:stop(force) validate('force', force, { 'number', 'boolean' }, true) diff --git a/src/gen/lint.lua b/src/gen/lint.lua index de2db2b302..1c70091b5f 100644 --- a/src/gen/lint.lua +++ b/src/gen/lint.lua @@ -274,10 +274,12 @@ function M.lint_quasi_keysets(source, funs) for _, p in ipairs(fun.params or {}) do if p.desc then local prev = nil --- @type string? - for name in p.desc:gmatch('\n%- ([%w_]+)') do + -- Capture the keyname with optional punctuation (`, "), so the sort includes surrounding + -- chars: backtick items group together, double-quote group together, etc. (Example: |Client:stop()|) + for name in p.desc:gmatch('\n%- (["`]?[%w_]+["`]?)') do -- Sort underscore-prefixed keys (e.g. "_cmdline_offset") at the end. - local prev_key = prev and prev:gsub('^_', '~') or nil - local name_key = name:gsub('^_', '~') + local prev_key = prev and prev:gsub('^([`"]?)_', '%1~') or nil + local name_key = name:gsub('^([`"]?)_', '%1~') if prev_key and name_key < prev_key then errors[#errors + 1] = fmt( '%s: %s(): param "%s": key "%s" should come before "%s" (sort alphabetically)', diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c index 7812ca3018..644c52f586 100644 --- a/src/nvim/api/autocmd.c +++ b/src/nvim/api/autocmd.c @@ -370,13 +370,13 @@ cleanup: /// - callback (`function|string?`) Lua function (or Vimscript function name, if string) /// called when the event(s) is triggered. Lua callback can return |lua-truthy| to delete /// the autocommand. Callback receives one argument, a table with keys: [event-args]() -/// - id: (`number`) Autocommand id -/// - event: (`vim.api.keyset.events`) Name of the triggered event |autocmd-events| -/// - group: (`number?`) Group id, if any -/// - file: (`string`) [] (not expanded to a full path) -/// - match: (`string`) [] (expanded to a full path) /// - buf: (`number`) [] /// - data: (`any`) Arbitrary data passed from [nvim_exec_autocmds()] [event-data]() +/// - event: (`vim.api.keyset.events`) Name of the triggered event |autocmd-events| +/// - file: (`string`) [] (not expanded to a full path) +/// - group: (`number?`) Group id, if any +/// - id: (`number`) Autocommand id +/// - match: (`string`) [] (expanded to a full path) /// - command (string?) Vim command executed on event. Not allowed with {callback}. /// - desc (`string?`) Description (for documentation and troubleshooting). /// - group (`string|integer?`) Group name or id to match against. diff --git a/src/nvim/api/command.c b/src/nvim/api/command.c index 41ff02cea6..2a04d3521c 100644 --- a/src/nvim/api/command.c +++ b/src/nvim/api/command.c @@ -977,35 +977,33 @@ static void build_cmdline_str(char **cmdlinep, exarg_T *eap, CmdParseInfo *cmdin /// Hello world! /// ``` /// -/// @param name Name of the new user command. Must begin with an uppercase letter. -/// @param cmd Replacement command to execute when this user command is executed. When called -/// from Lua, the command can also be a Lua function. The function is called with a -/// single table argument that contains the following keys: -/// - args: (string) The args passed to the command, if any [] -/// - bang: (boolean) "true" if the command was executed with a ! modifier [] -/// - count: (number) Any count supplied [] -/// - fargs: (table) The args split by unescaped whitespace (when more than one -/// argument is allowed), if any [] -/// - line1: (number) The starting line of the command range [] -/// - line2: (number) The final line of the command range [] -/// - mods: (string) Command modifiers, if any [] -/// - name: (string) Command name -/// - nargs: (string) Number of arguments allowed for the command -/// - range: (number) The number of items in the command range: 0, 1, or 2 [] -/// - reg: (string) The optional register, if specified [] -/// - smods: (table) Command modifiers in a structured format. Has the same -/// structure as the "mods" key of |nvim_parse_cmd()|. -/// @param opts Optional flags +/// @param name Command name. First char must be uppercase. +/// @param cmd Command or Lua function, executed when the command is invoked. Lua function +/// receives a table with keys: +/// - args: (string) Args passed to the command, if any. [] +/// - bang: (boolean) true if the command was executed with "!". [] +/// - count: (number) Count, if any. [] +/// - fargs: (table) Args split by unescaped whitespace (when more than one arg is +/// allowed), if any. [] +/// - line1: (number) Start of the command range. [] +/// - line2: (number) End of the command range. [] +/// - mods: (string) Command modifiers (unstructured string), if any. [] +/// - name: (string) Command name. +/// - nargs: (string) Number of arguments allowed by the command. |:command-nargs| +/// - range: (number) Number of items in the command range: 0, 1, or 2. [] +/// - reg: (string) Register name, if any. [] +/// - smods: (table) Command modifiers (structured), same as "mods" in |nvim_parse_cmd()|. +/// @param opts Optional flags: +/// - `addr` |:command-addr| +/// - `complete` |:command-complete| command or function |:command-completion-customlist|. +/// - `count` |:command-count| /// - `desc` (string) Command description. -/// - `force` (boolean, default true) Override any previous definition. -/// - `complete` |:command-complete| command or function like |:command-completion-customlist|. -/// - `nargs` Number of arguments allowed for the command |:command-nargs| -/// - `preview` (function) Preview handler for 'inccommand' |:command-preview| -/// - `range` see |:command-range| -/// - `count` see |:command-count| -/// - `addr` see |:command-addr| -/// - Set boolean |command-attributes| such as |:command-bang| or |:command-bar| to -/// true (but not |:command-buffer|, use |nvim_buf_create_user_command()| instead). +/// - `force` (boolean, default true) Override the existing definition, if any. +/// - `nargs` Number of arguments allowed by the command. |:command-nargs| +/// - `preview` (function) Preview handler for 'inccommand'. |:command-preview| +/// - `range` |:command-range| +/// - boolean |command-attributes| such as |:command-bang| or |:command-bar| (but +/// not |:command-buffer|, use |nvim_buf_create_user_command()| instead). /// @param[out] err Error details, if any. void nvim_create_user_command(uint64_t channel_id, String name, diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 8aab7e24e3..e40575a783 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -1630,9 +1630,9 @@ ArrayOf(DictAs(get_keymap)) nvim_get_keymap(String mode, Arena *arena) /// @param rhs Right-hand-side |{rhs}| of the mapping. /// @param opts Optional parameters map: Accepts all |:map-arguments| as keys except [], /// values are booleans (default false). Also: -/// - "noremap" disables |recursive_mapping|, like |:noremap| -/// - "desc" human-readable description. /// - "callback" Lua function called in place of {rhs}. +/// - "desc" human-readable description. +/// - "noremap" disables |recursive_mapping|, like |:noremap| /// - "replace_keycodes" (boolean) When "expr" is true, replace keycodes in the /// resulting string (see |nvim_replace_termcodes()|). Returning nil from the Lua /// "callback" is equivalent to returning an empty string. @@ -1685,22 +1685,22 @@ ArrayOf(Object, 2) nvim_get_api_info(uint64_t channel_id, Arena *arena) /// @param name Client short-name. Sets the `client.name` field of |nvim_get_chan_info()|. /// @param version Dict describing the version, with these /// (optional) keys: +/// - "commit" hash or similar identifier of commit /// - "major" major version (defaults to 0 if not set, for no release yet) /// - "minor" minor version /// - "patch" patch number /// - "prerelease" string describing a prerelease, like "dev" or "beta1" -/// - "commit" hash or similar identifier of commit /// @param type Must be one of the following values. Client libraries should /// default to "remote" unless overridden by the user. -/// - "remote" remote client connected "Nvim flavored" MessagePack-RPC (responses -/// must be in reverse order of requests). |msgpack-rpc| -/// - "msgpack-rpc" remote client connected to Nvim via fully MessagePack-RPC -/// compliant protocol. -/// - "ui" gui frontend /// - "embedder" application using Nvim as a component (for example, /// IDE/editor implementing a vim mode). /// - "host" plugin host, typically started by nvim +/// - "msgpack-rpc" remote client connected to Nvim via fully MessagePack-RPC +/// compliant protocol. /// - "plugin" single plugin, started by nvim +/// - "remote" remote client connected "Nvim flavored" MessagePack-RPC (responses +/// must be in reverse order of requests). |msgpack-rpc| +/// - "ui" gui frontend /// @param methods Builtin methods in the client. For a host, this does not /// include plugin methods which will be discovered later. /// The key should be the method name, the values are dicts with @@ -1715,11 +1715,11 @@ ArrayOf(Object, 2) nvim_get_api_info(uint64_t channel_id, Arena *arena) /// /// @param attributes Arbitrary string:string map of informal client properties. /// Suggested keys: -/// - "pid": Process id. -/// - "website": Client homepage URL (e.g. GitHub repository) /// - "license": License description ("Apache 2", "GPLv3", "MIT", …) /// - "logo": URI or path to image, preferably small logo or icon. /// .png or .svg format is preferred. +/// - "pid": Process id. +/// - "website": Client homepage URL (e.g. GitHub repository) /// /// @param[out] err Error details, if any void nvim_set_client_info(uint64_t channel_id, String name, Dict version, String type, Dict methods, diff --git a/src/nvim/api/vimscript.c b/src/nvim/api/vimscript.c index c210e429ed..983806a77f 100644 --- a/src/nvim/api/vimscript.c +++ b/src/nvim/api/vimscript.c @@ -357,18 +357,18 @@ typedef kvec_withinit_t(ExprASTConvStackItem, 16) ExprASTConvStack; /// /// @param[in] expr Expression to parse. Always treated as a single line. /// @param[in] flags Flags: -/// - "m" if multiple expressions in a row are allowed (only -/// the first one will be parsed), /// - "E" if EOC tokens are not allowed (determines whether /// they will stop parsing process or be recognized as an /// operator/space, though also yielding an error). /// - "l" when needing to start parsing with lvalues for /// ":let" or ":for". -/// Common flag sets: -/// - "m" to parse like for `":echo"`. -/// - "E" to parse like for `"="`. -/// - empty string for ":call". -/// - "lm" to parse for ":let". +/// - "m" if multiple expressions in a row are allowed (only +/// the first one will be parsed), +/// - Common flag sets: +/// - "E" to parse like for `"="`. +/// - "lm" to parse for ":let". +/// - "m" to parse like for `":echo"`. +/// - empty string for ":call". /// @param[in] hl If true, return value will also include "highlight" /// key containing array of 4-tuples (arrays) (Integer, /// Integer, Integer, String), where first three numbers diff --git a/src/nvim/vvars.lua b/src/nvim/vvars.lua index 63b7951b0e..b40d1350cc 100644 --- a/src/nvim/vvars.lua +++ b/src/nvim/vvars.lua @@ -450,9 +450,10 @@ M.vars = { useractive = { type = 'integer', desc = [=[ - Timestamp indicating the most recent user activity. - Updated every time a key is received from a UI - (TUI keystrokes or RPC |nvim_input()|). + Timestamp (nanoseconds since UNIX epoch) indicating the most + recent user activity, i.e. when a key is received from a UI + (TUI input or |nvim_input()|). + Initialized to 0 (no user activity since startup). Read-only. ]=],