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