docs(lua): more improvements (#24387)

* docs(lua): teach lua2dox how to table

* docs(lua): teach gen_vimdoc.py about local functions

No more need to mark local functions with @private

* docs(lua): mention @nodoc and @meta in dev-lua-doc

* fixup!

Co-authored-by: Justin M. Keyes <justinkz@gmail.com>

---------

Co-authored-by: Justin M. Keyes <justinkz@gmail.com>

37 files changed, 279 insertions, 497 deletions

diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index db878ac304..f36ef1df0a 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -233,6 +233,8 @@ Docstring format:
   - List-items start with `-` (useful to nest or "indent")
 - Use `<pre>` for code samples.
   Code samples can be annotated as `vim` or `lua`
+- Use `@nodoc` to prevent documentation generation.
+- Files which has `@meta` are only used for typing and documentation.
 
 Example: the help for |vim.paste()| is generated from a docstring decorating
 vim.paste in runtime/lua/vim/_editor.lua like this: >
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index fa109dbc26..edc9f50c8d 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -758,6 +758,24 @@ client_is_stopped({client_id})                   *vim.lsp.client_is_stopped()*
     Return: ~
         (boolean) stopped true if client is stopped, false otherwise.
 
+commands                                                    *vim.lsp.commands*
+    Registry for client side commands. This is an extension point for plugins
+    to handle custom commands which are not part of the core language server
+    protocol specification.
+
+    The registry is a table where the key is a unique command name, and the
+    value is a function which is called if any LSP action (code action, code
+    lenses, ...) triggers the command.
+
+    If a LSP response contains a command for which no matching entry is
+    available in this registry, the command will be executed via the LSP
+    server using `workspace/executeCommand`.
+
+    The first argument to the function will be the `Command`: Command title:
+    String command: String arguments?: any[]
+
+    The second argument is the `ctx` of |lsp-handler|
+
 formatexpr({opts})                                      *vim.lsp.formatexpr()*
     Provides an interface between the built-in client and a `formatexpr`
     function.
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index ac40d61e20..0b894897d1 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -591,16 +591,6 @@ If you want to exclude visual selections from highlighting on yank, use: >vim
     au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false}
 <
 
-vim.highlight.priorities                            *vim.highlight.priorities*
-
-    Table with default priorities used for highlighting:
-        • `syntax`: `50`, used for standard syntax highlighting
-        • `treesitter`: `100`, used for tree-sitter-based highlighting
-        • `semantic_tokens`: `125`, used for LSP semantic token highlighting
-        • `diagnostics`: `150`, used for code analysis such as diagnostics
-        • `user`: `200`, used for user-triggered highlights such as LSP document
-          symbols or `on_yank` autocommands
-
 vim.highlight.on_yank({opts})                        *vim.highlight.on_yank()*
     Highlight the yanked text
 
@@ -616,6 +606,15 @@ vim.highlight.on_yank({opts})                        *vim.highlight.on_yank()*
                 • priority integer priority (default
                   |vim.highlight.priorities|`.user`)
 
+vim.highlight.priorities                            *vim.highlight.priorities*
+    Table with default priorities used for highlighting:
+    • `syntax`: `50`, used for standard syntax highlighting
+    • `treesitter`: `100`, used for tree-sitter-based highlighting
+    • `semantic_tokens`: `125`, used for LSP semantic token highlighting
+    • `diagnostics`: `150`, used for code analysis such as diagnostics
+    • `user`: `200`, used for user-triggered highlights such as LSP document
+      symbols or `on_yank` autocommands
+
                                                        *vim.highlight.range()*
 vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts})
     Apply highlight group to range of text.
@@ -1189,15 +1188,6 @@ vim.v                                                                  *vim.v*
     |v:| variables.
     Invalid or unset key returns `nil`.
 
-vim.env                                                              *vim.env*
-    Environment variables defined in the editor session.
-    See |expand-env| and |:let-environment| for the Vimscript behavior.
-    Invalid or unset key returns `nil`.
-    Example: >lua
-        vim.env.FOO = 'bar'
-        print(vim.env.TERM)
-<
-
 ` `                                                                *lua-options*
                                                              *lua-vim-options*
                                                                  *lua-vim-set*
@@ -1221,62 +1211,6 @@ window-scoped options. Note that this must NOT be confused with
 |local-options| and |:setlocal|. There is also |vim.go| that only accesses the
 global value of a |global-local| option, see |:setglobal|.
 
-vim.o                                                                  *vim.o*
-    Get or set |options|. Like `:set`. Invalid key is an error.
-
-    Note: this works on both buffer-scoped and window-scoped options using the
-    current buffer and window.
-
-    Example: >lua
-        vim.o.cmdheight = 4
-        print(vim.o.columns)
-        print(vim.o.foo)     -- error: invalid key
-<
-
-vim.go                                                                *vim.go*
-    Get or set global |options|. Like `:setglobal`. Invalid key is
-    an error.
-
-    Note: this is different from |vim.o| because this accesses the global
-    option value and thus is mostly useful for use with |global-local|
-    options.
-
-    Example: >lua
-        vim.go.cmdheight = 4
-        print(vim.go.columns)
-        print(vim.go.bar)     -- error: invalid key
-<
-
-vim.bo[{bufnr}]                                                                *vim.bo*
-    Get or set buffer-scoped |options| for the buffer with number {bufnr}.
-    Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current
-    buffer is used. Invalid {bufnr} or key is an error.
-
-    Note: this is equivalent to both `:set` and `:setlocal`.
-
-    Example: >lua
-        local bufnr = vim.api.nvim_get_current_buf()
-        vim.bo[bufnr].buflisted = true    -- same as vim.bo.buflisted = true
-        print(vim.bo.comments)
-        print(vim.bo.baz)                 -- error: invalid key
-
-vim.wo[{winid}][{bufnr}]                                                       *vim.wo*
-    Get or set window-scoped |options| for the window with handle {winid} and
-    buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like
-    `:set` otherwise. If [{winid}] is omitted then the current window is
-    used. Invalid {winid}, {bufnr} or key is an error.
-
-    Note: only {bufnr} with value `0` (the current buffer in the window) is
-    supported.
-
-    Example: >lua
-        local winid = vim.api.nvim_get_current_win()
-        vim.wo[winid].number = true    -- same as vim.wo.number = true
-        print(vim.wo.foldmarker)
-        print(vim.wo.quux)             -- error: invalid key
-        vim.wo[winid][0].spell = false -- like ':setlocal nospell'
-<
-
 ` `                                                                       *vim.opt_local*
                                                                        *vim.opt_global*
                                                                               *vim.opt*
@@ -1419,11 +1353,81 @@ Option:remove({value})                                      *vim.opt:remove()*
     Parameters: ~
       • {value}  (string) Value to remove
 
+vim.bo                                                                *vim.bo*
+    Get or set buffer-scoped |options| for the buffer with number {bufnr}.
+    Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current
+    buffer is used. Invalid {bufnr} or key is an error.
+
+    Note: this is equivalent to both `:set` and `:setlocal`.
+
+    Example: >lua
+        local bufnr = vim.api.nvim_get_current_buf()
+        vim.bo[bufnr].buflisted = true    -- same as vim.bo.buflisted = true
+        print(vim.bo.comments)
+        print(vim.bo.baz)                 -- error: invalid key
+<
+
+    Parameters: ~
+      • {bufnr}  (integer|nil)
+
+vim.env                                                              *vim.env*
+    Environment variables defined in the editor session. See |expand-env| and
+    |:let-environment| for the Vimscript behavior. Invalid or unset key
+    returns `nil` . Example: >lua
+        vim.env.FOO = 'bar'
+        print(vim.env.TERM)
+<
+
+    Parameters: ~
+      • {var}  (string)
+
+vim.go                                                                *vim.go*
+    Get or set global |options|. Like `:setglobal`. Invalid key is an error.
+
+    Note: this is different from |vim.o| because this accesses the global
+    option value and thus is mostly useful for use with |global-local|
+    options.
+
+    Example: >lua
+        vim.go.cmdheight = 4
+        print(vim.go.columns)
+        print(vim.go.bar)     -- error: invalid key
+<
+
+vim.o                                                                  *vim.o*
+    Get or set |options|. Like `:set`. Invalid key is an error.
+
+    Note: this works on both buffer-scoped and window-scoped options using the
+    current buffer and window.
+
+    Example: >lua
+        vim.o.cmdheight = 4
+        print(vim.o.columns)
+        print(vim.o.foo)     -- error: invalid key
+<
+
+vim.wo                                                                *vim.wo*
+    Get or set window-scoped |options| for the window with handle {winid} and
+    buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like
+    `:set` otherwise. If [{winid}] is omitted then the current window is used.
+    Invalid {winid}, {bufnr} or key is an error.
+
+    Note: only {bufnr} with value `0` (the current buffer in the window) is
+    supported.
+
+    Example: >lua
+        local winid = vim.api.nvim_get_current_win()
+        vim.wo[winid].number = true    -- same as vim.wo.number = true
+        print(vim.wo.foldmarker)
+        print(vim.wo.quux)             -- error: invalid key
+        vim.wo[winid][0].spell = false -- like ':setlocal nospell'
+<
+
 
 ==============================================================================
 Lua module: vim                                                      *lua-vim*
 
-vim.cmd({command})                                                 *vim.cmd()*
+vim.cmd                                                            *vim.cmd()*
     Execute Vim script commands.
 
     Note that `vim.cmd` can be indexed with a command name to return a
@@ -1468,10 +1472,6 @@ vim.cmd({command})                                                 *vim.cmd()*
     See also: ~
       • |ex-cmd-index|
 
-                                             *vim.connection_failure_errmsg()*
-vim.connection_failure_errmsg({consequence})
-    TODO: Documentation
-
 vim.defer_fn({fn}, {timeout})                                 *vim.defer_fn()*
     Defers calling {fn} until {timeout} ms passes.
 
@@ -1501,7 +1501,7 @@ vim.deprecate({name}, {alternative}, {version}, {plugin}, {backtrace})
     Return: ~
         (string|nil) # Deprecated message, or nil if no message was shown.
 
-vim.inspect({object}, {options})                               *vim.inspect()*
+vim.inspect                                                    *vim.inspect()*
     Gets a human-readable representation of the given object.
 
     See also: ~
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index bb0aa97a0d..4372aef7b3 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -54,6 +54,7 @@ vim._extra = {
   inspect_pos = true,
 }
 
+--- @private
 vim.log = {
   levels = {
     TRACE = 0,
@@ -187,9 +188,7 @@ end
 ---@see |vim.print()|
 ---@see https://github.com/kikito/inspect.lua
 ---@see https://github.com/mpeterv/vinspect
-local function inspect(object, options) -- luacheck: no unused
-  error(object, options) -- Stub for gen_vimdoc.py
-end
+vim.inspect = vim.inspect
 
 do
   local tdots, tick, got_line1, undo_started, trailing_nl = 0, 0, false, false, false
@@ -328,6 +327,7 @@ function vim.schedule_wrap(cb)
 end
 
 -- vim.fn.{func}(...)
+---@private
 vim.fn = setmetatable({}, {
   __index = function(t, key)
     local _fn
@@ -345,10 +345,13 @@ vim.fn = setmetatable({}, {
   end,
 })
 
+--- @private
 vim.funcref = function(viml_func_name)
   return vim.fn[viml_func_name]
 end
 
+local VIM_CMD_ARG_MAX = 20
+
 --- Execute Vim script commands.
 ---
 --- Note that `vim.cmd` can be indexed with a command name to return a callable function to the
@@ -389,12 +392,6 @@ end
 ---                            If a table, executes a single command. In this case, it is an alias
 ---                            to |nvim_cmd()| where `opts` is empty.
 ---@see |ex-cmd-index|
-function vim.cmd(command) -- luacheck: no unused
-  error(command) -- Stub for gen_vimdoc.py
-end
-
-local VIM_CMD_ARG_MAX = 20
-
 vim.cmd = setmetatable({}, {
   __call = function(_, command)
     if type(command) == 'table' then
@@ -435,7 +432,6 @@ vim.cmd = setmetatable({}, {
 do
   local validate = vim.validate
 
-  ---@private
   local function make_dict_accessor(scope, handle)
     validate({
       scope = { scope, 's' },
@@ -745,7 +741,6 @@ function vim._expand_pat(pat, env)
   end
 
   local keys = {}
-  ---@private
   local function insert_keys(obj)
     for k, _ in pairs(obj) do
       if type(k) == 'string' and string.sub(k, 1, string.len(match_part)) == match_part then
@@ -1008,7 +1003,6 @@ end
 function vim._init_default_mappings()
   -- mappings
 
-  ---@private
   local function region_chunks(region)
     local chunks = {}
     local maxcol = vim.v.maxcol
@@ -1020,7 +1014,6 @@ function vim._init_default_mappings()
     return chunks
   end
 
-  ---@private
   local function _visual_search(cmd)
     assert(cmd == '/' or cmd == '?')
     vim.api.nvim_feedkeys('\27', 'nx', true) -- Escape visual mode.
@@ -1037,7 +1030,6 @@ function vim._init_default_mappings()
     vim.api.nvim_feedkeys(search_cmd, 'nx', true)
   end
 
-  ---@private
   local function map(mode, lhs, rhs)
     vim.keymap.set(mode, lhs, rhs, { desc = 'Nvim builtin' })
   end
diff --git a/runtime/lua/vim/_inspector.lua b/runtime/lua/vim/_inspector.lua
index ecd39c35bc..3f7b9d2c23 100644
--- a/runtime/lua/vim/_inspector.lua
+++ b/runtime/lua/vim/_inspector.lua
@@ -56,7 +56,6 @@ function vim.inspect_pos(bufnr, row, col, filter)
   }
 
   -- resolve hl links
-  ---@private
   local function resolve_hl(data)
     if data.hl_group then
       local hlid = vim.api.nvim_get_hl_id_by_name(data.hl_group)
@@ -91,7 +90,6 @@ function vim.inspect_pos(bufnr, row, col, filter)
   end
 
   --- Convert an extmark tuple into a table
-  --- @private
   local function to_map(extmark)
     extmark = {
       id = extmark[1],
@@ -107,7 +105,6 @@ function vim.inspect_pos(bufnr, row, col, filter)
   end
 
   --- Check if an extmark overlaps this position
-  --- @private
   local function is_here(extmark)
     return (row >= extmark.row and row <= extmark.end_row) -- within the rows of the extmark
       and (row > extmark.row or col >= extmark.col) -- either not the first row, or in range of the col
@@ -148,17 +145,14 @@ function vim.show_pos(bufnr, row, col, filter)
 
   local lines = { {} }
 
-  ---@private
   local function append(str, hl)
     table.insert(lines[#lines], { str, hl })
   end
 
-  ---@private
   local function nl()
     table.insert(lines, {})
   end
 
-  ---@private
   local function item(data, comment)
     append('  - ')
     append(data.hl_group, data.hl_group)
diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua
index 6dbe4cf64a..d54e8b447c 100644
--- a/runtime/lua/vim/_options.lua
+++ b/runtime/lua/vim/_options.lua
@@ -92,15 +92,6 @@
 ---vim.v                                                                  *vim.v*
 ---    |v:| variables.
 ---    Invalid or unset key returns `nil`.
----
----vim.env                                                              *vim.env*
----    Environment variables defined in the editor session.
----    See |expand-env| and |:let-environment| for the Vimscript behavior.
----    Invalid or unset key returns `nil`.
----    Example: >lua
----        vim.env.FOO = 'bar'
----        print(vim.env.TERM)
----<
 ---</pre>
 
 local api = vim.api
@@ -118,7 +109,6 @@ local key_value_options = {
 
 --- Convert a vimoption_T style dictionary to the correct OptionType associated with it.
 ---@return string
----@private
 local function get_option_metatype(name, info)
   if info.type == 'string' then
     if info.flaglist then
@@ -143,6 +133,14 @@ local options_info = setmetatable({}, {
   end,
 })
 
+---Environment variables defined in the editor session.
+---See |expand-env| and |:let-environment| for the Vimscript behavior.
+---Invalid or unset key returns `nil`.
+---Example: <pre>lua
+---    vim.env.FOO = 'bar'
+---    print(vim.env.TERM)
+---</pre>
+---@param var string
 vim.env = setmetatable({}, {
   __index = function(_, k)
     local v = vim.fn.getenv(k)
@@ -157,7 +155,6 @@ vim.env = setmetatable({}, {
   end,
 })
 
----@private
 local function opt_validate(option_name, target_scope)
   local scope = options_info[option_name].scope
   if scope ~= target_scope then
@@ -174,7 +171,6 @@ local function opt_validate(option_name, target_scope)
   end
 end
 
----@private
 local function new_buf_opt_accessor(bufnr)
   return setmetatable({}, {
     __index = function(_, k)
@@ -192,7 +188,6 @@ local function new_buf_opt_accessor(bufnr)
   })
 end
 
----@private
 local function new_win_opt_accessor(winid, bufnr)
   return setmetatable({}, {
     __index = function(_, k)
@@ -253,19 +248,15 @@ end
 ---global value of a |global-local| option, see |:setglobal|.
 ---</pre>
 
----@addtogroup lua-vimscript
----@brief <pre>help
----vim.o                                                                  *vim.o*
----    Get or set |options|. Like `:set`. Invalid key is an error.
+---Get or set |options|. Like `:set`. Invalid key is an error.
 ---
----    Note: this works on both buffer-scoped and window-scoped options using the
----    current buffer and window.
+---Note: this works on both buffer-scoped and window-scoped options using the
+---current buffer and window.
 ---
----    Example: >lua
----        vim.o.cmdheight = 4
----        print(vim.o.columns)
----        print(vim.o.foo)     -- error: invalid key
----<
+---Example: <pre>lua
+---    vim.o.cmdheight = 4
+---    print(vim.o.columns)
+---    print(vim.o.foo)     -- error: invalid key
 ---</pre>
 vim.o = setmetatable({}, {
   __index = function(_, k)
@@ -276,21 +267,17 @@ vim.o = setmetatable({}, {
   end,
 })
 
----@addtogroup lua-vimscript
----@brief <pre>help
----vim.go                                                                *vim.go*
----    Get or set global |options|. Like `:setglobal`. Invalid key is
----    an error.
----
----    Note: this is different from |vim.o| because this accesses the global
----    option value and thus is mostly useful for use with |global-local|
----    options.
----
----    Example: >lua
----        vim.go.cmdheight = 4
----        print(vim.go.columns)
----        print(vim.go.bar)     -- error: invalid key
----<
+---Get or set global |options|. Like `:setglobal`. Invalid key is
+---an error.
+---
+---Note: this is different from |vim.o| because this accesses the global
+---option value and thus is mostly useful for use with |global-local|
+---options.
+---
+---Example: <pre>lua
+---    vim.go.cmdheight = 4
+---    print(vim.go.columns)
+---    print(vim.go.bar)     -- error: invalid key
 ---</pre>
 vim.go = setmetatable({}, {
   __index = function(_, k)
@@ -301,41 +288,36 @@ vim.go = setmetatable({}, {
   end,
 })
 
----@addtogroup lua-vimscript
----@brief <pre>help
----vim.bo[{bufnr}]                                                                *vim.bo*
----    Get or set buffer-scoped |options| for the buffer with number {bufnr}.
----    Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current
----    buffer is used. Invalid {bufnr} or key is an error.
----
----    Note: this is equivalent to both `:set` and `:setlocal`.
----
----    Example: >lua
----        local bufnr = vim.api.nvim_get_current_buf()
----        vim.bo[bufnr].buflisted = true    -- same as vim.bo.buflisted = true
----        print(vim.bo.comments)
----        print(vim.bo.baz)                 -- error: invalid key
+---Get or set buffer-scoped |options| for the buffer with number {bufnr}.
+---Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current
+---buffer is used. Invalid {bufnr} or key is an error.
+---
+---Note: this is equivalent to both `:set` and `:setlocal`.
+---
+---Example: <pre>lua
+---    local bufnr = vim.api.nvim_get_current_buf()
+---    vim.bo[bufnr].buflisted = true    -- same as vim.bo.buflisted = true
+---    print(vim.bo.comments)
+---    print(vim.bo.baz)                 -- error: invalid key
 ---</pre>
+---@param bufnr integer|nil
 vim.bo = new_buf_opt_accessor()
 
----@addtogroup lua-vimscript
----@brief <pre>help
----vim.wo[{winid}][{bufnr}]                                                       *vim.wo*
----    Get or set window-scoped |options| for the window with handle {winid} and
----    buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like
----    `:set` otherwise. If [{winid}] is omitted then the current window is
----    used. Invalid {winid}, {bufnr} or key is an error.
----
----    Note: only {bufnr} with value `0` (the current buffer in the window) is
----    supported.
----
----    Example: >lua
----        local winid = vim.api.nvim_get_current_win()
----        vim.wo[winid].number = true    -- same as vim.wo.number = true
----        print(vim.wo.foldmarker)
----        print(vim.wo.quux)             -- error: invalid key
----        vim.wo[winid][0].spell = false -- like ':setlocal nospell'
----<
+---Get or set window-scoped |options| for the window with handle {winid} and
+---buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like
+---`:set` otherwise. If [{winid}] is omitted then the current window is
+---used. Invalid {winid}, {bufnr} or key is an error.
+---
+---Note: only {bufnr} with value `0` (the current buffer in the window) is
+---supported.
+---
+---Example: <pre>lua
+---    local winid = vim.api.nvim_get_current_win()
+---    vim.wo[winid].number = true    -- same as vim.wo.number = true
+---    print(vim.wo.foldmarker)
+---    print(vim.wo.quux)             -- error: invalid key
+---    vim.wo[winid][0].spell = false -- like ':setlocal nospell'
+---
 ---</pre>
 vim.wo = new_win_opt_accessor()
 
@@ -348,7 +330,6 @@ vim.wo = new_win_opt_accessor()
 ---@brief ]]
 
 --- Preserves the order and does not mutate the original list
---- @private
 local function remove_duplicate_values(t)
   local result, seen = {}, {}
   for _, v in ipairs(t) do
@@ -364,7 +345,6 @@ end
 
 -- Check whether the OptionTypes is allowed for vim.opt
 -- If it does not match, throw an error which indicates which option causes the error.
---- @private
 local function assert_valid_value(name, value, types)
   local type_of_value = type(value)
   for _, valid_type in ipairs(types) do
@@ -383,17 +363,14 @@ local function assert_valid_value(name, value, types)
   )
 end
 
---- @private
 local function passthrough(_, x)
   return x
 end
 
---- @private
 local function tbl_merge(left, right)
   return vim.tbl_extend('force', left, right)
 end
 
---- @private
 local function tbl_remove(t, value)
   if type(value) == 'string' then
     t[value] = nil
@@ -475,7 +452,6 @@ local to_vim_value = {
 }
 
 --- Convert a Lua value to a vimoption_T value
---- @private
 local function convert_value_to_vim(name, info, value)
   if value == nil then
     return vim.NIL
@@ -591,7 +567,6 @@ local to_lua_value = {
 }
 
 --- Converts a vimoption_T style value to a Lua value
---- @private
 local function convert_value_to_lua(info, option_value)
   return to_lua_value[info.metatype](info, option_value)
 end
@@ -618,7 +593,6 @@ local prepend_methods = {
 }
 
 --- Handles the '^' operator
---- @private
 local function prepend_value(info, current, new)
   return prepend_methods[info.metatype](
     convert_value_to_lua(info, current),
@@ -648,7 +622,6 @@ local add_methods = {
 }
 
 --- Handles the '+' operator
---- @private
 local function add_value(info, current, new)
   return add_methods[info.metatype](
     convert_value_to_lua(info, current),
@@ -656,7 +629,6 @@ local function add_value(info, current, new)
   )
 end
 
---- @private
 local function remove_one_item(t, val)
   if vim.tbl_islist(t) then
     local remove_index = nil
@@ -700,16 +672,13 @@ local remove_methods = {
 }
 
 --- Handles the '-' operator
---- @private
 local function remove_value(info, current, new)
   return remove_methods[info.metatype](convert_value_to_lua(info, current), new)
 end
 
---- @private
 local function create_option_accessor(scope)
   local option_mt
 
-  --- @private
   local function make_option(name, value)
     local info = assert(options_info[name], 'Not a valid option name: ' .. name)
 
@@ -923,6 +892,11 @@ function Option:prepend(value) end -- luacheck: no unused
 ---@diagnostic disable-next-line:unused-local used for gen_vimdoc
 function Option:remove(value) end -- luacheck: no unused
 
+---@private
 vim.opt = create_option_accessor()
+
+---@private
 vim.opt_local = create_option_accessor('local')
+
+---@private
 vim.opt_global = create_option_accessor('global')
diff --git a/runtime/lua/vim/_system.lua b/runtime/lua/vim/_system.lua
index ff566866c0..e6dab90425 100644