From 2739ab485e4e76f24bf776c5169d0f4037554f7d Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Sun, 28 Sep 2025 23:57:59 -0400 Subject: [PATCH] docs: json, tests, lsp #35754 Close #35926 Close #35818 Co-authored-by: skewb1k Co-authored-by: glepnir --- runtime/doc/api.txt | 6 ++-- runtime/doc/index.txt | 22 +++++++------- runtime/doc/lsp.txt | 49 +++++++++++++++++++------------ runtime/doc/lua.txt | 34 ++++++++++----------- runtime/doc/news-0.9.txt | 17 ++++------- runtime/doc/options.txt | 1 + runtime/doc/vimfn.txt | 28 +++++++++--------- runtime/lua/vim/_meta/api.lua | 10 +++---- runtime/lua/vim/_meta/builtin.lua | 2 +- runtime/lua/vim/_meta/json.lua | 45 ++++++++++++++++++---------- runtime/lua/vim/_meta/options.lua | 1 + runtime/lua/vim/_meta/vimfn.lua | 28 +++++++++--------- runtime/lua/vim/lsp.lua | 42 ++++++++++++++++---------- src/gen/gen_help_html.lua | 2 +- src/nvim/api/vim.c | 10 +++---- src/nvim/eval.lua | 16 ++++++++-- src/nvim/options.lua | 1 + test/README.md | 10 +++++++ 18 files changed, 186 insertions(+), 138 deletions(-) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 3b9e20bd7d..fdd6c1e945 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -696,8 +696,8 @@ nvim_echo({chunks}, {history}, {opts}) *nvim_echo()* • running: The progress is ongoing • failed: The progress item failed • cancel: The progressing process should be canceled. - note: Cancel needs to be handled by progress initiator - by listening for the `Progress` event + NOTE: Cancel must be handled by progress initiator by + listening for the `Progress` event • percent: How much progress is done on the progress message • data: dictionary containing additional information @@ -1500,7 +1500,7 @@ nvim_set_current_tabpage({tabpage}) *nvim_set_current_tabpage()* • {tabpage} (`integer`) |tab-ID| to focus nvim_set_current_win({window}) *nvim_set_current_win()* - Sets the current window (and tabpage, implicitly). + Navigates to the given window (and tabpage, implicitly). Attributes: ~ not allowed when |textlock| is active or in the |cmdwin| diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt index 4bfb8e5fd4..e3c22416b7 100644 --- a/runtime/doc/index.txt +++ b/runtime/doc/index.txt @@ -19,7 +19,7 @@ For a list of Vim variables see |vim-variable|. ============================================================================== 1. Insert mode *insert-index* -tag char action in Insert mode ~ +Tag Char Insert-mode action ~ ------------------------------------------------------------------------------ ~ |i_CTRL-@| CTRL-@ insert previously inserted text and stop insert @@ -182,7 +182,7 @@ SECTION a section that possibly starts with '}' instead of '{' note: 1 = cursor movement command; 2 = can be undone/redone -tag char note action in Normal mode ~ +Tag Char Note Normal-mode action ~ ------------------------------------------------------------------------------ ~ CTRL-@ not used |CTRL-A| CTRL-A 2 add N to number at/after cursor @@ -471,7 +471,7 @@ tag char note action in Normal mode ~ These can be used after an operator or in Visual mode to select an object. -tag command action in op-pending and Visual mode ~ +Tag Command Op-pending and Visual-mode action ~ ------------------------------------------------------------------------------ ~ |v_aquote| a" double quoted string |v_a'| a' single quoted string @@ -513,7 +513,7 @@ tag command action in op-pending and Visual mode ~ ============================================================================== 2.2 Window commands *CTRL-W* -tag command action in Normal mode ~ +Tag Command Normal-mode action ~ ------------------------------------------------------------------------------ ~ |CTRL-W_CTRL-B| CTRL-W CTRL-B same as "CTRL-W b" |CTRL-W_CTRL-C| CTRL-W CTRL-C no-op @@ -611,7 +611,7 @@ tag command action in Normal mode ~ ============================================================================== 2.3 Square bracket commands *[* *]* -tag char note action in Normal mode ~ +Tag Char Note Normal-mode action ~ ------------------------------------------------------------------------------ ~ |[_CTRL-D| [ CTRL-D jump to first #define found in current and included files matching the word under the @@ -701,7 +701,7 @@ tag char note action in Normal mode ~ ============================================================================== 2.4 Commands starting with 'g' *g* -tag char note action in Normal mode ~ +Tag Char Note Normal-mode action ~ ------------------------------------------------------------------------------ ~ |g_CTRL-G| g CTRL-G show information about current cursor position @@ -802,7 +802,7 @@ tag char note action in Normal mode ~ ============================================================================== 2.5 Commands starting with 'z' *z* -tag char note action in Normal mode ~ +Tag Char Note Normal-mode action ~ ------------------------------------------------------------------------------ ~ |z| z redraw, cursor line to top of window, cursor on first non-blank @@ -876,7 +876,7 @@ tag char note action in Normal mode ~ These can be used after an operator, but before a {motion} has been entered. -tag char action in Operator-pending mode ~ +Tag Char Operator-pending-mode action ~ ------------------------------------------------------------------------------ ~ |o_v| v force operator to work charwise |o_V| V force operator to work linewise @@ -888,7 +888,7 @@ tag char action in Operator-pending mode ~ Most commands in Visual mode are the same as in Normal mode. The ones listed here are those that are different. -tag command note action in Visual mode ~ +Tag Command Note Visual-mode action ~ ------------------------------------------------------------------------------ ~ |v_CTRL-\_CTRL-N| CTRL-\ CTRL-N stop Visual mode |v_CTRL-\_CTRL-G| CTRL-\ CTRL-G go to Normal mode @@ -1007,7 +1007,7 @@ Normal characters are inserted at the current cursor position. "Completion" below refers to context-sensitive completion. It will complete file names, tags, commands etc. as appropriate. -tag command action in Command-line editing mode ~ +Tag Command Command-line editing-mode action ~ ------------------------------------------------------------------------------ ~ CTRL-@ not used |c_CTRL-A| CTRL-A do completion on the pattern in front of the @@ -1131,7 +1131,7 @@ This is a brief but complete listing of all the ":" commands, without mentioning any arguments. The optional part of the command name is inside []. The commands are sorted on the non-optional part of their name. -tag command action ~ +Tag Command Action ~ ------------------------------------------------------------------------------ ~ |:| : nothing |:range| :{range} go to last line in {range} diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index de1f96a8cc..71239ff3c4 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -769,9 +769,22 @@ Lua module: vim.lsp *lsp-core* See `cmd` in |vim.lsp.ClientConfig|. See also `reuse_client` to dynamically decide (per-buffer) when `cmd` should be re-invoked. - • {filetypes}? (`string[]`) Filetypes the client will attach to, if - activated by `vim.lsp.enable()`. If not provided, the - client will attach to all filetypes. + • {filetypes}? (`string[]`) Filetypes the client will attach to, or + `nil` for ALL filetypes. To match files by name, + pattern, or contents, you can define a custom + filetype using |vim.filetype.add()|: >lua + vim.filetype.add({ + filename = { + ['my_filename'] = 'my_filetype1', + }, + pattern = { + ['.*/etc/my_file_pattern/.*'] = 'my_filetype2', + }, + }) + vim.lsp.config('…', { + filetypes = { 'my_filetype1', 'my_filetype2' }, + } +< • {reuse_client}? (`fun(client: vim.lsp.Client, config: vim.lsp.ClientConfig): boolean`) Predicate which decides if a client should be re-used. Used on all running clients. The default @@ -793,23 +806,21 @@ Lua module: vim.lsp *lsp-core* defined. The list order decides priority. To indicate "equal priority", specify names in a nested list `{ { 'a.txt', 'b.lua' }, ... }`. - - For each item, Nvim will search upwards (from the - buffer file) for that marker, or list of markers; - search stops at the first directory containing that - marker, and the directory is used as the root dir - (workspace folder). - - Example: Find the first ancestor directory containing - file or directory "stylua.toml"; if not found, find - the first ancestor containing ".git": >lua - root_markers = { 'stylua.toml', '.git' } + • For each item, Nvim will search upwards (from the + buffer file) for that marker, or list of markers; + search stops at the first directory containing that + marker, and the directory is used as the root dir + (workspace folder). + • Example: Find the first ancestor directory + containing file or directory "stylua.toml"; if not + found, find the first ancestor containing ".git": > + root_markers = { 'stylua.toml', '.git' } < - - Example: Find the first ancestor directory containing - EITHER "stylua.toml" or ".luarc.json"; if not found, - find the first ancestor containing ".git": >lua - root_markers = { { 'stylua.toml', '.luarc.json' }, '.git' } + • Example: Find the first ancestor directory + containing EITHER "stylua.toml" or ".luarc.json"; + if not found, find the first ancestor containing + ".git": > + root_markers = { { 'stylua.toml', '.luarc.json' }, '.git' } < diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 7e30f94753..270aa72de8 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -873,7 +873,7 @@ vim.wait({time}, {callback}, {interval}, {fast_only}) *vim.wait()* Parameters: ~ • {time} (`integer`) Number of milliseconds to wait - • {callback} (`fun(): boolean?`) Optional callback. Waits until + • {callback} (`fun(): boolean, ...?`) Optional callback. Waits until {callback} returns true • {interval} (`integer?`) (Approximate) number of milliseconds to wait between polls @@ -3356,12 +3356,10 @@ vim.json.decode({str}, {opts}) *vim.json.decode()* Parameters: ~ • {str} (`string`) Stringified JSON data. - • {opts} (`table?`) Options table with keys: - • luanil: (table) Table with keys: - • object: (boolean) When true, converts `null` in JSON - objects to Lua `nil` instead of |vim.NIL|. - • array: (boolean) When true, converts `null` in JSON arrays - to Lua `nil` instead of |vim.NIL|. + • {opts} (`table?`) A table with the following fields: + • {luanil}? (`{ object?: boolean, array?: boolean }`, default: + `nil`) Convert `null` in JSON objects and/or arrays to Lua + `nil` instead of |vim.NIL|. Return: ~ (`any`) @@ -3369,14 +3367,14 @@ vim.json.decode({str}, {opts}) *vim.json.decode()* vim.json.encode({obj}, {opts}) *vim.json.encode()* Encodes (or "packs") a Lua object to stringified JSON. - Example: use the `indent` flag to implement a basic 'formatexpr' for JSON, - so you can use |gq| with a motion to format JSON in a buffer. (The motion - must operate on a valid JSON object.) >lua + Example: Implement a basic 'formatexpr' for JSON, so |gq| with a motion + formats JSON in a buffer. (The motion must operate on a valid JSON + object.) >lua function _G.fmt_json() local indent = vim.bo.expandtab and (' '):rep(vim.o.shiftwidth) or '\t' local lines = vim.api.nvim_buf_get_lines(0, vim.v.lnum - 1, vim.v.lnum + vim.v.count - 1, true) local o = vim.json.decode(table.concat(lines, '\n')) - local stringified = vim.json.encode(o, { indent = indent }) + local stringified = vim.json.encode(o, { indent = indent, sort_keys = true }) lines = vim.split(stringified, '\n') vim.api.nvim_buf_set_lines(0, vim.v.lnum - 1, vim.v.count, true, lines) end @@ -3385,14 +3383,14 @@ vim.json.encode({obj}, {opts}) *vim.json.encode()* Parameters: ~ • {obj} (`any`) - • {opts} (`table?`) Options table with keys: - • escape_slash: (boolean) (default false) Escape slash + • {opts} (`table?`) A table with the following fields: + • {escape_slash}? (`boolean`, default: `false`) Escape slash characters "/" in string values. - • indent: (string) (default "") String used for indentation at - each nesting level. If non-empty enables newlines and a - space after colons. - • sort_keys: (boolean) (default false) Sort object keys in - alphabetical order. + • {indent}? (`string`, default: `""`) If non-empty, the + returned JSON is formatted with newlines and whitespace, + where `indent` defines the whitespace at each nesting level. + • {sort_keys}? (`boolean`, default: `false`) Sort object keys + in alphabetical order. Return: ~ (`string`) diff --git a/runtime/doc/news-0.9.txt b/runtime/doc/news-0.9.txt index 0dbc60f1cb..d30c5a7aba 100644 --- a/runtime/doc/news-0.9.txt +++ b/runtime/doc/news-0.9.txt @@ -71,18 +71,16 @@ The following new APIs or features were added. the contents >lua vim.treesitter.start() < - Note: Highlighted code examples are only available in the Nvim manual, not - in help files taken from Vim. The treesitter `vimdoc` parser is also work in - progress and not guaranteed to correctly highlight every help file in the - wild. + • Note: Highlighted code examples are only available in the Nvim manual, not + in help files taken from Vim. The treesitter `vimdoc` parser is also work + in progress and not guaranteed to correctly highlight every help file in + the wild. • Added support for semantic token highlighting to the LSP client. This functionality is enabled by default when a client that supports this feature is attached to a buffer. Opt-out can be performed by deleting the `semanticTokensProvider` from the LSP client's {server_capabilities} in the - `LspAttach` callback. - - See |lsp-semantic-highlight| for more information. + `LspAttach` callback. See |lsp-semantic-highlight| for more information. • |vim.inspect_pos()|, |vim.show_pos()| and |:Inspect| allow a user to get or show items at a given buffer position. Currently this includes treesitter captures, @@ -102,12 +100,9 @@ The following new APIs or features were added. trusted and, if so, returns the file's contents. Used by 'exrc' • EditorConfig support is now builtin. This is enabled by default and happens - automatically. To disable it, users should add >lua - + automatically. To disable it, add the following to your |config|: >lua vim.g.editorconfig = false < - (or the Vimscript equivalent) to their |config| file. - • A new environment variable named NVIM_APPNAME enables configuring the directories where Nvim should find its configuration and state files. See `:help $NVIM_APPNAME` . diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index c83f29e258..4f35ca6c4b 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -2891,6 +2891,7 @@ A jump table for the options with a short description can be found at |Q_op|. foldclose FoldColumn |hl-FoldColumn| foldsep FoldColumn |hl-FoldColumn| diff DiffDelete |hl-DiffDelete| + msgsep MsgSeparator |hl-MsgSeparator| eob EndOfBuffer |hl-EndOfBuffer| lastline NonText |hl-NonText| trunc one of the many Popup menu highlighting groups like diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt index ea191cb960..f15bc1deff 100644 --- a/runtime/doc/vimfn.txt +++ b/runtime/doc/vimfn.txt @@ -6280,7 +6280,7 @@ match({expr}, {pat} [, {start} [, {count}]]) *match()* • {count} (`integer?`) Return: ~ - (`any`) + (`integer`) *matchadd()* *E798* *E799* *E801* *E957* matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) @@ -6346,10 +6346,10 @@ matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) • {pattern} (`string`) • {priority} (`integer?`) • {id} (`integer?`) - • {dict} (`string?`) + • {dict} (`table?`) Return: ~ - (`any`) + (`integer`) matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) *matchaddpos()* Same as |matchadd()|, but requires a list of positions {pos} @@ -6393,10 +6393,10 @@ matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) *matchaddpos()* • {pos} (`any[]`) • {priority} (`integer?`) • {id} (`integer?`) - • {dict} (`string?`) + • {dict} (`table?`) Return: ~ - (`any`) + (`integer|table`) matcharg({nr}) *matcharg()* Selects the {nr} match item, as set with a |:match|, @@ -6414,7 +6414,7 @@ matcharg({nr}) *matcharg()* • {nr} (`integer`) Return: ~ - (`any`) + (`string[]`) matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}]) *matchbufline()* Returns the |List| of matches in lines from {lnum} to {end} in @@ -6468,7 +6468,7 @@ matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}]) *matchbufline()* • {dict} (`table?`) Return: ~ - (`any`) + (`string[]`) matchdelete({id} [, {win}]) *matchdelete()* *E802* *E803* Deletes a match with ID {id} previously defined by |matchadd()| @@ -6511,7 +6511,7 @@ matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()* • {count} (`integer?`) Return: ~ - (`any`) + (`integer`) matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()* If {list} is a list of strings, then returns a |List| with all @@ -6582,7 +6582,7 @@ matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()* • {dict} (`table?`) Return: ~ - (`any`) + (`table`) matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()* Same as |matchfuzzy()|, but returns the list of matched @@ -6612,7 +6612,7 @@ matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()* • {dict} (`table?`) Return: ~ - (`any`) + (`table`) matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()* Same as |match()|, but return a |List|. The first item in the @@ -6633,7 +6633,7 @@ matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()* • {count} (`integer?`) Return: ~ - (`any`) + (`string[]`) matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()* Same as |match()|, but return the matched string. Example: >vim @@ -6655,7 +6655,7 @@ matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()* • {count} (`integer?`) Return: ~ - (`any`) + (`string`) matchstrlist({list}, {pat} [, {dict}]) *matchstrlist()* Returns the |List| of matches in {list} where {pat} matches. @@ -6696,7 +6696,7 @@ matchstrlist({list}, {pat} [, {dict}]) *matchstrlist()* • {dict} (`table?`) Return: ~ - (`any`) + (`string[]`) matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()* Same as |matchstr()|, but return the matched string, the start @@ -6723,7 +6723,7 @@ matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()* • {count} (`integer?`) Return: ~ - (`any`) + (`table`) max({expr}) *max()* Return the maximum value of all items in {expr}. Example: >vim diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 44ffa7d70d..873ae6e516 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1117,11 +1117,9 @@ function vim.api.nvim_del_var(name) end --- - success: The progress item completed successfully --- - running: The progress is ongoing --- - failed: The progress item failed ---- - cancel: The progressing process should be canceled. ---- note: Cancel needs to be handled by progress ---- initiator by listening for the `Progress` event ---- - percent: How much progress is done on the progress ---- message +--- - cancel: The progressing process should be canceled. NOTE: Cancel must be handled by +--- progress initiator by listening for the `Progress` event +--- - percent: How much progress is done on the progress message --- - data: dictionary containing additional information --- @return integer|string # Message id. --- - -1 means nvim_echo didn't show a message @@ -2116,7 +2114,7 @@ function vim.api.nvim_set_current_line(line) end --- @param tabpage integer `tab-ID` to focus function vim.api.nvim_set_current_tabpage(tabpage) end ---- Sets the current window (and tabpage, implicitly). +--- Navigates to the given window (and tabpage, implicitly). --- --- @param window integer `window-ID` to focus function vim.api.nvim_set_current_win(window) end diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua index 899229edef..50b242f765 100644 --- a/runtime/lua/vim/_meta/builtin.lua +++ b/runtime/lua/vim/_meta/builtin.lua @@ -209,7 +209,7 @@ function vim.schedule(fn) end --- ``` --- --- @param time integer Number of milliseconds to wait ---- @param callback? fun(): boolean Optional callback. Waits until {callback} returns true +--- @param callback? fun(): boolean, ... Optional callback. Waits until {callback} returns true --- @param interval? integer (Approximate) number of milliseconds to wait between polls --- @param fast_only? boolean If true, only |api-fast| events will be processed. --- @return boolean, nil|-1|-2, ... diff --git a/runtime/lua/vim/_meta/json.lua b/runtime/lua/vim/_meta/json.lua index a149d24dec..567ecb0a50 100644 --- a/runtime/lua/vim/_meta/json.lua +++ b/runtime/lua/vim/_meta/json.lua @@ -5,6 +5,30 @@ vim.json = {} -- luacheck: no unused args +--- @class vim.json.decode.Opts +--- @inlinedoc +--- +--- Convert `null` in JSON objects and/or arrays to Lua `nil` instead of |vim.NIL|. +--- (default: `nil`) +--- @field luanil? { object?: boolean, array?: boolean } + +--- @class vim.json.encode.Opts +--- @inlinedoc +--- +--- Escape slash characters "/" in string values. +--- (default: `false`) +--- @field escape_slash? boolean +--- +--- +--- If non-empty, the returned JSON is formatted with newlines and whitespace, where `indent` +--- defines the whitespace at each nesting level. +--- (default: `""`) +--- @field indent? string +--- +--- Sort object keys in alphabetical order. +--- (default: `false`) +--- @field sort_keys? boolean + ---@brief --- --- This module provides encoding and decoding of Lua objects to and @@ -24,26 +48,21 @@ vim.json = {} --- ``` --- ---@param str string Stringified JSON data. ----@param opts? table Options table with keys: ---- - luanil: (table) Table with keys: ---- - object: (boolean) When true, converts `null` in JSON objects ---- to Lua `nil` instead of |vim.NIL|. ---- - array: (boolean) When true, converts `null` in JSON arrays ---- to Lua `nil` instead of |vim.NIL|. +---@param opts? vim.json.decode.Opts ---@return any function vim.json.decode(str, opts) end --- Encodes (or "packs") a Lua object to stringified JSON. --- ---- Example: use the `indent` flag to implement a basic 'formatexpr' for JSON, so you can use |gq| ---- with a motion to format JSON in a buffer. (The motion must operate on a valid JSON object.) +--- Example: Implement a basic 'formatexpr' for JSON, so |gq| with a motion formats JSON in +--- a buffer. (The motion must operate on a valid JSON object.) --- --- ```lua --- function _G.fmt_json() --- local indent = vim.bo.expandtab and (' '):rep(vim.o.shiftwidth) or '\t' --- local lines = vim.api.nvim_buf_get_lines(0, vim.v.lnum - 1, vim.v.lnum + vim.v.count - 1, true) --- local o = vim.json.decode(table.concat(lines, '\n')) ---- local stringified = vim.json.encode(o, { indent = indent }) +--- local stringified = vim.json.encode(o, { indent = indent, sort_keys = true }) --- lines = vim.split(stringified, '\n') --- vim.api.nvim_buf_set_lines(0, vim.v.lnum - 1, vim.v.count, true, lines) --- end @@ -51,12 +70,6 @@ function vim.json.decode(str, opts) end --- ``` --- ---@param obj any ----@param opts? table Options table with keys: ---- - escape_slash: (boolean) (default false) Escape slash ---- characters "/" in string values. ---- - indent: (string) (default "") String used for indentation at each nesting level. ---- If non-empty enables newlines and a space after colons. ---- - sort_keys: (boolean) (default false) Sort object ---- keys in alphabetical order. +---@param opts? vim.json.encode.Opts ---@return string function vim.json.encode(obj, opts) end diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index c7290df25b..c9a590f5c7 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -2612,6 +2612,7 @@ vim.bo.ft = vim.bo.filetype --- foldclose FoldColumn `hl-FoldColumn` --- foldsep FoldColumn `hl-FoldColumn` --- diff DiffDelete `hl-DiffDelete` +--- msgsep MsgSeparator `hl-MsgSeparator` --- eob EndOfBuffer `hl-EndOfBuffer` --- lastline NonText `hl-NonText` --- trunc one of the many Popup menu highlighting groups like diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua index 028a23d053..436da3ae3f 100644 --- a/runtime/lua/vim/_meta/vimfn.lua +++ b/runtime/lua/vim/_meta/vimfn.lua @@ -5697,7 +5697,7 @@ function vim.fn.mapset(dict) end --- @param pat string --- @param start? integer --- @param count? integer ---- @return any +--- @return integer function vim.fn.match(expr, pat, start, count) end --- Defines a pattern to be highlighted in the current window (a @@ -5761,8 +5761,8 @@ function vim.fn.match(expr, pat, start, count) end --- @param pattern string --- @param priority? integer --- @param id? integer ---- @param dict? string ---- @return any +--- @param dict? table +--- @return integer function vim.fn.matchadd(group, pattern, priority, id, dict) end --- Same as |matchadd()|, but requires a list of positions {pos} @@ -5805,8 +5805,8 @@ function vim.fn.matchadd(group, pattern, priority, id, dict) end --- @param pos any[] --- @param priority? integer --- @param id? integer ---- @param dict? string ---- @return any +--- @param dict? table +--- @return integer|table function vim.fn.matchaddpos(group, pos, priority, id, dict) end --- Selects the {nr} match item, as set with a |:match|, @@ -5821,7 +5821,7 @@ function vim.fn.matchaddpos(group, pos, priority, id, dict) end --- to three matches. |matchadd()| does not have this limitation. --- --- @param nr integer ---- @return any +--- @return string[] function vim.fn.matcharg(nr) end --- Returns the |List| of matches in lines from {lnum} to {end} in @@ -5872,7 +5872,7 @@ function vim.fn.matcharg(nr) end --- @param lnum string|integer --- @param end_ string|integer --- @param dict? table ---- @return any +--- @return string[] function vim.fn.matchbufline(buf, pat, lnum, end_, dict) end --- Deletes a match with ID {id} previously defined by |matchadd()| @@ -5909,7 +5909,7 @@ function vim.fn.matchdelete(id, win) end --- @param pat string --- @param start? integer --- @param count? integer ---- @return any +--- @return integer function vim.fn.matchend(expr, pat, start, count) end --- If {list} is a list of strings, then returns a |List| with all @@ -5977,7 +5977,7 @@ function vim.fn.matchend(expr, pat, start, count) end --- @param list any[] --- @param str string --- @param dict? table ---- @return any +--- @return table function vim.fn.matchfuzzy(list, str, dict) end --- Same as |matchfuzzy()|, but returns the list of matched @@ -6004,7 +6004,7 @@ function vim.fn.matchfuzzy(list, str, dict) end --- @param list any[] --- @param str string --- @param dict? table ---- @return any +--- @return table function vim.fn.matchfuzzypos(list, str, dict) end --- Same as |match()|, but return a |List|. The first item in the @@ -6022,7 +6022,7 @@ function vim.fn.matchfuzzypos(list, str, dict) end --- @param pat string --- @param start? integer --- @param count? integer ---- @return any +--- @return string[] function vim.fn.matchlist(expr, pat, start, count) end --- Same as |match()|, but return the matched string. Example: >vim @@ -6041,7 +6041,7 @@ function vim.fn.matchlist(expr, pat, start, count) end --- @param pat string --- @param start? integer --- @param count? integer ---- @return any +--- @return string function vim.fn.matchstr(expr, pat, start, count) end --- Returns the |List| of matches in {list} where {pat} matches. @@ -6079,7 +6079,7 @@ function vim.fn.matchstr(expr, pat, start, count) end --- @param list string[] --- @param pat string --- @param dict? table ---- @return any +--- @return string[] function vim.fn.matchstrlist(list, pat, dict) end --- Same as |matchstr()|, but return the matched string, the start @@ -6103,7 +6103,7 @@ function vim.fn.matchstrlist(list, pat, dict) end --- @param pat string --- @param start? integer --- @param count? integer ---- @return any +--- @return table function vim.fn.matchstrpos(expr, pat, start, count) end --- Return the maximum value of all items in {expr}. Example: >vim diff --git a/runtime/lua/vim/lsp.lua b/runtime/lua/vim/lsp.lua index 7e3d8c6811..f922bc8074 100644 --- a/runtime/lua/vim/lsp.lua +++ b/runtime/lua/vim/lsp.lua @@ -199,8 +199,21 @@ end --- See also `reuse_client` to dynamically decide (per-buffer) when `cmd` should be re-invoked. --- @field cmd? string[]|fun(dispatchers: vim.lsp.rpc.Dispatchers, config: vim.lsp.ClientConfig): vim.lsp.rpc.PublicClient --- ---- Filetypes the client will attach to, if activated by `vim.lsp.enable()`. If not provided, the ---- client will attach to all filetypes. +--- Filetypes the client will attach to, or `nil` for ALL filetypes. To match files by name, +--- pattern, or contents, you can define a custom filetype using |vim.filetype.add()|: +--- ```lua +--- vim.filetype.add({ +--- filename = { +--- ['my_filename'] = 'my_filetype1', +--- }, +--- pattern = { +--- ['.*/etc/my_file_pattern/.*'] = 'my_filetype2', +--- }, +--- }) +--- vim.lsp.config('…', { +--- filetypes = { 'my_filetype1', 'my_filetype2' }, +--- } +--- ``` --- @field filetypes? string[] --- --- Predicate which decides if a client should be re-used. Used on all running clients. The default @@ -219,22 +232,19 @@ end --- Filename(s) (".git/", "package.json", …) used to decide the workspace root. Unused if `root_dir` --- is defined. The list order decides priority. To indicate "equal priority", specify names in --- a nested list `{ { 'a.txt', 'b.lua' }, ... }`. ---- ---- For each item, Nvim will search upwards (from the buffer file) for that marker, or list of ---- markers; search stops at the first directory containing that marker, and the directory is used ---- as the root dir (workspace folder). ---- ---- Example: Find the first ancestor directory containing file or directory "stylua.toml"; if not ---- found, find the first ancestor containing ".git": ---- ```lua +--- - For each item, Nvim will search upwards (from the buffer file) for that marker, or list of +--- markers; search stops at the first directory containing that marker, and the directory is used +--- as the root dir (workspace folder). +--- - Example: Find the first ancestor directory containing file or directory "stylua.toml"; if not +--- found, find the first ancestor containing ".git": +--- ``` --- root_markers = { 'stylua.toml', '.git' } ---- ``` ---- ---- Example: Find the first ancestor directory containing EITHER "stylua.toml" or ".luarc.json"; if ---- not found, find the first ancestor containing ".git": ---- ```lua +--- ``` +--- - Example: Find the first ancestor directory containing EITHER "stylua.toml" or ".luarc.json"; +--- if not found, find the first ancestor containing ".git": +--- ``` --- root_markers = { { 'stylua.toml', '.luarc.json' }, '.git' } ---- ``` +--- ``` --- --- @field root_markers? (string|string[])[] diff --git a/src/gen/gen_help_html.lua b/src/gen/gen_help_html.lua index 91744e77a5..48dbcf9a5b 100644 --- a/src/gen/gen_help_html.lua +++ b/src/gen/gen_help_html.lua @@ -1094,7 +1094,7 @@ local function gen_helptags_json(fname) -- "foo.html#tag" t[tag] = ('%s#%s'):format(htmlpage, url_encode(tag)) end - tofile(fname, vim.json.encode(t)) + tofile(fname, vim.json.encode(t, { indent = ' ', sort_keys = true })) end local function gen_css(fname) diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index d91f068bec..260886dc69 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -770,11 +770,9 @@ void nvim_set_vvar(String name, Object value, Error *err) /// - success: The progress item completed successfully /// - running: The progress is ongoing /// - failed: The progress item failed -/// - cancel: The progressing process should be canceled. -/// note: Cancel needs to be handled by progress -/// initiator by listening for the `Progress` event -/// - percent: How much progress is done on the progress -/// message +/// - cancel: The progressing process should be canceled. NOTE: Cancel must be handled by +/// progress initiator by listening for the `Progress` event +/// - percent: How much progress is done on the progress message /// - data: dictionary containing additional information /// @return Message id. /// - -1 means nvim_echo didn't show a message @@ -927,7 +925,7 @@ Window nvim_get_current_win(void) return curwin->handle; } -/// Sets the current window (and tabpage, implicitly). +/// Navigates to the given window (and tabpage, implicitly). /// /// @param window |window-ID| to focus /// @param[out] err Error details, if any diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua index 4b58eabed8..a34237abee 100644 --- a/src/nvim/eval.lua +++ b/src/nvim/eval.lua @@ -7011,6 +7011,7 @@ M.funcs = { { 'count', 'integer' }, }, signature = 'match({expr}, {pat} [, {start} [, {count}]])', + returns = 'integer', }, matchadd = { args = { 2, 5 }, @@ -7080,10 +7081,11 @@ M.funcs = { { 'pattern', 'string' }, { 'priority', 'integer' }, { 'id', 'integer' }, - { 'dict', 'string' }, + { 'dict', 'table' }, }, signature = 'matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]])', tags = { 'E798', 'E799', 'E801', 'E957' }, + returns = 'integer', }, matchaddpos = { args = { 2, 5 }, @@ -7132,9 +7134,10 @@ M.funcs = { { 'pos', 'any[]' }, { 'priority', 'integer' }, { 'id', 'integer' }, - { 'dict', 'string' }, + { 'dict', 'table' }, }, signature = 'matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]])', + returns = 'integer|table', }, matcharg = { args = 1, @@ -7155,6 +7158,7 @@ M.funcs = { name = 'matcharg', params = { { 'nr', 'integer' } }, signature = 'matcharg({nr})', + returns = 'string[]', }, matchbufline = { args = { 4, 5 }, @@ -7212,6 +7216,7 @@ M.funcs = { { 'dict', 'table' }, }, signature = 'matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}])', + returns = 'string[]', }, matchdelete = { args = { 1, 2 }, @@ -7261,6 +7266,7 @@ M.funcs = { { 'count', 'integer' }, }, signature = 'matchend({expr}, {pat} [, {start} [, {count}]])', + returns = 'integer', }, matchfuzzy = { args = { 2, 3 }, @@ -7331,6 +7337,7 @@ M.funcs = { name = 'matchfuzzy', params = { { 'list', 'any[]' }, { 'str', 'string' }, { 'dict', 'table' } }, signature = 'matchfuzzy({list}, {str} [, {dict}])', + returns = 'table', }, matchfuzzypos = { args = { 2, 3 }, @@ -7360,6 +7367,7 @@ M.funcs = { name = 'matchfuzzypos', params = { { 'list', 'any[]' }, { 'str', 'string' }, { 'dict', 'table' } }, signature = 'matchfuzzypos({list}, {str} [, {dict}])', + returns = 'table', }, matchlist = { args = { 2, 4 }, @@ -7385,6 +7393,7 @@ M.funcs = { { 'count', 'integer' }, }, signature = 'matchlist({expr}, {pat} [, {start} [, {count}]])', + returns = 'string[]', }, matchstr = { args = { 2, 4 }, @@ -7411,6 +7420,7 @@ M.funcs = { { 'count', 'integer' }, }, signature = 'matchstr({expr}, {pat} [, {start} [, {count}]])', + returns = 'string', }, matchstrlist = { args = { 2, 3 }, @@ -7451,6 +7461,7 @@ M.funcs = { name = 'matchstrlist', params = { { 'list', 'string[]' }, { 'pat', 'string' }, { 'dict', 'table' } }, signature = 'matchstrlist({list}, {pat} [, {dict}])', + returns = 'string[]', }, matchstrpos = { args = { 2, 4 }, @@ -7482,6 +7493,7 @@ M.funcs = { { 'count', 'integer' }, }, signature = 'matchstrpos({expr}, {pat} [, {start} [, {count}]])', + returns = 'table', }, max = { args = 1, diff --git a/src/nvim/options.lua b/src/nvim/options.lua index bd53a42461..7cb74396bc 100644 --- a/src/nvim/options.lua +++ b/src/nvim/options.lua @@ -3292,6 +3292,7 @@ local options = { foldclose FoldColumn |hl-FoldColumn| foldsep FoldColumn |hl-FoldColumn| diff DiffDelete |hl-DiffDelete| + msgsep MsgSeparator |hl-MsgSeparator| eob EndOfBuffer |hl-EndOfBuffer| lastline NonText |hl-NonText| trunc one of the many Popup menu highlighting groups like diff --git a/test/README.md b/test/README.md index c1ad26a396..456f598e71 100644 --- a/test/README.md +++ b/test/README.md @@ -417,6 +417,16 @@ by the semantic component they are testing. sense, before creating a new one. +Fixing tests +============ + +> Nvim session T123 took 2000 milliseconds to exit +> This indicates a likely problem with the test even if it passed! + +This may indicate a leak, because Nvim waits on uv handles before exiting. +Example: https://github.com/neovim/neovim/pull/35768 + + Lint ====