docs: json, tests, lsp #35754

Close #35926
Close #35818

Co-authored-by: skewb1k <skewb1kunix@gmail.com>
Co-authored-by: glepnir <glephunter@gmail.com>

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
+                       NOTE: Cancel must be handled by progress initiator by
-                       by listening for the `Progress` event
+                       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|

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<CR>|		z<CR>		   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}

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
+      • {filetypes}?     (`string[]`) Filetypes the client will attach to, or
-                         activated by `vim.lsp.enable()`. If not provided, the
+                         `nil` for ALL filetypes. To match files by name,
-                         client will attach to all filetypes.
+                         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,22 +806,20 @@ 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
-                         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
-                         Example: Find the first ancestor directory containing
+                           containing file or directory "stylua.toml"; if not
-                         file or directory "stylua.toml"; if not found, find
+                           found, find the first ancestor containing ".git": >
-                         the first ancestor containing ".git": >lua
                            root_markers = { 'stylua.toml', '.git' }
 <
-
+                         • Example: Find the first ancestor directory
-                         Example: Find the first ancestor directory containing
+                           containing EITHER "stylua.toml" or ".luarc.json";
-                         EITHER "stylua.toml" or ".luarc.json"; if not found,
+                           if not found, find the first ancestor containing
-                         find the first ancestor containing ".git": >lua
+                           ".git": >
                            root_markers = { { 'stylua.toml', '.luarc.json' }, '.git' }
 <
 

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<string,any>?`) Options table with keys:
+      • {opts}  (`table?`) A table with the following fields:
-                • luanil: (table) Table with keys:
+                • {luanil}? (`{ object?: boolean, array?: boolean }`, default:
-                  • object: (boolean) When true, converts `null` in JSON
+                  `nil`) Convert `null` in JSON objects and/or arrays to Lua
-                    objects to Lua `nil` instead of |vim.NIL|.
+                  `nil` instead of |vim.NIL|.
-                  • array: (boolean) When true, converts `null` in JSON 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,
+    Example: Implement a basic 'formatexpr' for JSON, so |gq| with a motion
-    so you can use |gq| with a motion to format JSON in a buffer. (The motion
+    formats JSON in a buffer. (The motion must operate on a valid JSON
-    must operate on a valid JSON object.) >lua
+    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<string,any>?`) Options table with keys:
+      • {opts}  (`table?`) A table with the following fields:
-                • escape_slash: (boolean) (default false) Escape slash
+                • {escape_slash}? (`boolean`, default: `false`) Escape slash
                   characters "/" in string values.
-                • indent: (string) (default "") String used for indentation at
+                • {indent}? (`string`, default: `""`) If non-empty, the
-                  each nesting level. If non-empty enables newlines and a
+                  returned JSON is formatted with newlines and whitespace,
-                  space after colons.
+                  where `indent` defines the whitespace at each nesting level.
-                • sort_keys: (boolean) (default false) Sort object keys in
+                • {sort_keys}? (`boolean`, default: `false`) Sort object keys
-                  alphabetical order.
+                  in alphabetical order.
 
     Return: ~
         (`string`)

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
+  • 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
+    in help files taken from Vim. The treesitter `vimdoc` parser is also work
-  progress and not guaranteed to correctly highlight every help file in the
+    in progress and not guaranteed to correctly highlight every help file in
-  wild.
+    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.
+  `LspAttach` callback. See |lsp-semantic-highlight| for more information.
-
-  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` .

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

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

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.
+---   - cancel: The progressing process should be canceled. NOTE: Cancel must be handled by
----             note: Cancel needs to be handled by progress
+---     progress initiator by listening for the `Progress` event
----             initiator by listening for the `Progress` event
+--- - percent: How much progress is done on the progress message
---- - 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

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, ...

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<string,any> Options table with keys:
+---@param opts? vim.json.decode.Opts
----                               - 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|.
 ---@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|
+--- Example: Implement a basic 'formatexpr' for JSON, so |gq| with a motion formats JSON in
---- with a motion to format JSON in a buffer. (The motion must operate on a valid JSON object.)
+--- 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<string,any> Options table with keys:
+---@param opts? vim.json.encode.Opts
----                                 - 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.
 ---@return string
 function vim.json.encode(obj, opts) end

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

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
+--- @param dict? table
---- @return any
+--- @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
+--- @param dict? table
---- @return any
+--- @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

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
+--- Filetypes the client will attach to, or `nil` for ALL filetypes. To match files by name,
---- client will attach to all filetypes.
+--- 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,20 +232,17 @@ 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
---- 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
---- 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' }
 ---   ```
----
+--- - Example: Find the first ancestor directory containing EITHER "stylua.toml" or ".luarc.json";
---- Example: Find the first ancestor directory containing EITHER "stylua.toml" or ".luarc.json"; if
+---   if not found, find the first ancestor containing ".git":
---- not found, find the first ancestor containing ".git":
+---   ```
---- ```lua
 ---   root_markers = { { 'stylua.toml', '.luarc.json' }, '.git' }
 ---   ```
 ---

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)

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.
+///            - cancel: The progressing process should be canceled. NOTE: Cancel must be handled by
-///                      note: Cancel needs to be handled by progress
+///              progress initiator by listening for the `Progress` event
-///                      initiator by listening for the `Progress` event
+///          - percent: How much progress is done on the progress message
-///          - 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

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,

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

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
 ====