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>

1 files changed, 6 insertions, 14 deletions

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