fix(vim.json)!: remove global options, "null", "array_mt" #24070

Problem:
- `vim.json` exposes various global options which:
  - affect all Nvim Lua plugins (especially the LSP client)
  - are undocumented and untested
  - can cause confusing problems such as: https://github.com/codota/tabnine-nvim/commit/cc76ae3abe2f129d44b5a8edee2529e0ee0dcf69
- `vim.json` exposes redundant mechanisms:
  - `vim.json.null` is redundant with `vim.NIL`.
  - `array_mt` is redundant because Nvim uses a metatable
    (`vim.empty_dict()`) for empty dict instead, which `vim.json` is
    configured to use by default (see `as_empty_dict`).
    Example:
    ```
    :lua vim.print(vim.json.decode('{"bar":[],"foo":{}}'))
    --> { bar = {},  foo = vim.empty_dict() }
    ```
    Thus we don't need to also decorate empty arrays with `array_mt`.

Solution:
Remove the functions from the public vim.json interface.
Comment-out the implementation code to minimize drift from upstream.

TODO:
- Expose the options as arguments to `vim.json.new()`

2 files changed, 21 insertions, 3 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 1110fb7fc3..80ef2e358c 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -747,9 +747,22 @@ vim.json.encode({obj})                                       *vim.json.encode*
 vim.json.decode({str}[, {opts}])                             *vim.json.decode*
     Decodes (or "unpacks") the JSON-encoded {str} to a Lua object.
 
-    {opts} is a table with the key `luanil = { object: bool, array: bool }`
-    that controls whether `null` in JSON objects or arrays should be converted
-    to Lua `nil` instead of `vim.NIL`.
+    - Decodes JSON "null" as |vim.NIL| (controllable by {opts}, see below).
+    - Decodes empty object as |vim.empty_dict()|.
+    - Decodes empty array as `{}` (empty Lua table).
+
+    Example: >lua
+    :lua vim.print(vim.json.decode('{"bar":[],"foo":{},"zub":null}'))
+    --> { bar = {}, foo = vim.empty_dict(), zub = vim.NIL }
+<
+    Parameters: ~
+      • {str}    Stringified JSON data.
+      • {opts}   Options map keys:
+                 • luanil: { object: bool, array: bool }
+                   • `luanil.object=true` converts `null` in JSON objects to
+                     Lua `nil` instead of `vim.NIL`.
+                   • `luanil.array=true` converts `null` in JSON arrays to Lua
+                     `nil` instead of `vim.NIL`.
 
 ------------------------------------------------------------------------------
 VIM.SPELL                                                          *lua-spell*
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 2a25edc4eb..550b69010d 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -43,6 +43,11 @@ The following changes may require adaptations in user config or plugins.
 
 • Renamed `vim.treesitter.playground` to `vim.treesitter.dev`.
 
+• Removed functions from the |vim.json| module:
+  • Unnecessary, undocumented functions which caused global side-effects.
+  • `vim.json.null` is redundant with `vim.NIL`.
+  • `vim.json.array_mt` (and related) is redundant with `vim.empty_dict()`.
+
 ==============================================================================
 NEW FEATURES                                                    *news-features*