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>

runtime/lua/vim/treesitter/dev.lua

@@ -42,7 +42,6 @@ local TSTreeView = {}
 ---@param injections table<integer,TSP.Node> Mapping of node ids to root nodes of injected language trees (see
 ---                        explanation above)
 ---@param tree TSP.Node[] Output table containing a list of tables each representing a node in the tree
----@private
 local function traverse(node, depth, lang, injections, tree)
   local injection = injections[node:id()]
   if injection then
@@ -141,7 +140,6 @@ end
 
 local decor_ns = api.nvim_create_namespace('ts.dev')
 
----@private
 ---@param lnum integer
 ---@param col integer
 ---@param end_lnum integer

runtime/lua/vim/treesitter/highlighter.lua

@@ -17,6 +17,7 @@ local query = vim.treesitter.query
 local TSHighlighter = rawget(vim.treesitter, 'TSHighlighter') or {}
 TSHighlighter.__index = TSHighlighter
 
+--- @nodoc
 TSHighlighter.active = TSHighlighter.active or {}
 
 ---@class TSHighlighterQuery
@@ -205,7 +206,6 @@ function TSHighlighter:get_query(lang)
   return self._queries[lang]
 end
 
----@private
 ---@param self TSHighlighter
 ---@param buf integer
 ---@param line integer

runtime/lua/vim/treesitter/language.lua

@@ -104,7 +104,6 @@ function M.add(lang, opts)
   vim._ts_add_language(path, lang, symbol_name)
 end
 
---- @private
 --- @param x string|string[]
 --- @return string[]
 local function ensure_list(x)

runtime/lua/vim/treesitter/languagetree.lua

@@ -164,7 +164,6 @@ function LanguageTree:_set_logger()
   self._parser:_set_logger(log_lex, log_parse, self._logger)
 end
 
----@private
 ---Measure execution time of a function
 ---@generic R1, R2, R3
 ---@param f fun(): R1, R2, R2
@@ -444,7 +443,6 @@ function LanguageTree:destroy()
   end
 end
 
----@private
 ---@param region Range6[]
 local function region_tostr(region)
   if #region == 0 then
@@ -560,7 +558,6 @@ function LanguageTree:included_regions()
   return regions
 end
 
----@private
 ---@param node TSNode
 ---@param source string|integer
 ---@param metadata TSMetadata
@@ -600,7 +597,6 @@ end
 
 ---@alias TSInjection table<string,table<integer,TSInjectionElem>>
 
----@private
 ---@param t table<integer,TSInjection>
 ---@param tree_index integer
 ---@param pattern integer
@@ -963,7 +959,6 @@ function LanguageTree:register_cbs(cbs, recursive)
   end
 end
 
----@private
 ---@param tree TSTree
 ---@param range Range
 ---@return boolean

runtime/lua/vim/treesitter/query.lua

@@ -15,7 +15,6 @@ Query.__index = Query
 ---@class TSQueryModule
 local M = {}
 
----@private
 ---@param files string[]
 ---@return string[]
 local function dedupe_files(files)
@@ -33,7 +32,6 @@ local function dedupe_files(files)
   return result
 end
 
----@private
 local function safe_read(filename, read_quantifier)
   local file, err = io.open(filename, 'r')
   if not file then
@@ -44,7 +42,6 @@ local function safe_read(filename, read_quantifier)
   return content
 end
 
----@private
 --- Adds {ilang} to {base_langs}, only if {ilang} is different than {lang}
 ---
 ---@return boolean true If lang == ilang
@@ -153,7 +150,6 @@ function M.get_files(lang, query_name, is_included)
   return query_files
 end
 
----@private
 ---@param filenames string[]
 ---@return string
 local function read_query_files(filenames)
@@ -335,7 +331,6 @@ local predicate_handlers = {
 
   ['match?'] = (function()
     local magic_prefixes = { ['\\v'] = true, ['\\m'] = true, ['\\M'] = true, ['\\V'] = true }
-    ---@private
     local function check_magic(str)
       if string.len(str) < 2 or magic_prefixes[string.sub(str, 1, 2)] then
         return str
@@ -624,12 +619,10 @@ function M.list_predicates()
   return vim.tbl_keys(predicate_handlers)
 end
 
----@private
 local function xor(x, y)
   return (x or y) and not (x and y)
 end
 
----@private
 local function is_directive(name)
   return string.sub(name, -1) == '!'
 end
@@ -700,7 +693,6 @@ end
 --- Returns the start and stop value if set else the node's range.
 -- When the node's range is used, the stop is incremented by 1
 -- to make the search inclusive.
----@private
 ---@param start integer
 ---@param stop integer
 ---@param node TSNode
@@ -750,7 +742,6 @@ function Query:iter_captures(node, source, start, stop)
   start, stop = value_or_node_range(start, stop, node)
 
   local raw_iter = node:_rawquery(self.query, true, start, stop)
-  ---@private
   local function iter()
     local capture, captured_node, match = raw_iter()
     local metadata = {}