docs: json, tests, lsp #35754

Close #35926
Close #35818

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

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

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:
----                               - 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<string,any> 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

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

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[])[]