fix(treesitter): annotations

- Begin using `@package` in place of `@private` for functions
that are accessed internally but outside their defined class.

- Rename Node -> TSP.Node

runtime/lua/vim/treesitter.lua

@@ -30,8 +30,6 @@ setmetatable(M, {
   end,
 })
 
----@diagnostic disable:invisible
-
 --- Creates a new parser
 ---
 --- It is not recommended to use this; use |get_parser()| instead.
@@ -132,7 +130,7 @@ function M.get_parser(bufnr, lang, opts)
   return parsers[bufnr]
 end
 
----@private
+---@package
 ---@param bufnr (integer|nil) Buffer number
 ---@return boolean
 function M._has_parser(bufnr)
@@ -276,7 +274,7 @@ function M.get_captures_at_pos(bufnr, row, col)
         end
       end
     end
-  end, true)
+  end)
   return matches
 end
 

runtime/lua/vim/treesitter/_fold.lua

@@ -3,7 +3,7 @@ local Query = require('vim.treesitter.query')
 
 local api = vim.api
 
----@class FoldInfo
+---@class TS.FoldInfo
 ---@field levels table<integer,string>
 ---@field levels0 table<integer,integer>
 ---@field private start_counts table<integer,integer>
@@ -11,6 +11,7 @@ local api = vim.api
 local FoldInfo = {}
 FoldInfo.__index = FoldInfo
 
+---@private
 function FoldInfo.new()
   return setmetatable({
     start_counts = {},
@@ -20,6 +21,7 @@ function FoldInfo.new()
   }, FoldInfo)
 end
 
+---@package
 ---@param srow integer
 ---@param erow integer
 function FoldInfo:invalidate_range(srow, erow)
@@ -31,6 +33,7 @@ function FoldInfo:invalidate_range(srow, erow)
   end
 end
 
+---@package
 ---@param srow integer
 ---@param erow integer
 function FoldInfo:remove_range(srow, erow)
@@ -42,6 +45,7 @@ function FoldInfo:remove_range(srow, erow)
   end
 end
 
+---@package
 ---@param srow integer
 ---@param erow integer
 function FoldInfo:add_range(srow, erow)
@@ -53,22 +57,26 @@ function FoldInfo:add_range(srow, erow)
   end
 end
 
+---@package
 ---@param lnum integer
 function FoldInfo:add_start(lnum)
   self.start_counts[lnum] = (self.start_counts[lnum] or 0) + 1
 end
 
+---@package
 ---@param lnum integer
 function FoldInfo:add_stop(lnum)
   self.stop_counts[lnum] = (self.stop_counts[lnum] or 0) + 1
 end
 
+---@packag
 ---@param lnum integer
 ---@return integer
 function FoldInfo:get_start(lnum)
   return self.start_counts[lnum] or 0
 end
 
+---@package
 ---@param lnum integer
 ---@return integer
 function FoldInfo:get_stop(lnum)
@@ -84,7 +92,7 @@ local function trim_level(level)
 end
 
 ---@param bufnr integer
----@param info FoldInfo
+---@param info TS.FoldInfo
 ---@param srow integer?
 ---@param erow integer?
 local function get_folds_levels(bufnr, info, srow, erow)
@@ -161,7 +169,7 @@ end
 
 local M = {}
 
----@type table<integer,FoldInfo>
+---@type table<integer,TS.FoldInfo>
 local foldinfos = {}
 
 local function recompute_folds()
@@ -178,7 +186,7 @@ local function recompute_folds()
 end
 
 ---@param bufnr integer
----@param foldinfo FoldInfo
+---@param foldinfo TS.FoldInfo
 ---@param tree_changes Range4[]
 local function on_changedtree(bufnr, foldinfo, tree_changes)
   -- For some reason, queries seem to use the old buffer state in on_bytes.
@@ -193,7 +201,7 @@ local function on_changedtree(bufnr, foldinfo, tree_changes)
 end
 
 ---@param bufnr integer
----@param foldinfo FoldInfo
+---@param foldinfo TS.FoldInfo
 ---@param start_row integer
 ---@param old_row integer
 ---@param new_row integer
@@ -212,13 +220,13 @@ local function on_bytes(bufnr, foldinfo, start_row, old_row, new_row)
   end
 end
 
+---@package
 ---@param lnum integer|nil
 ---@return string
 function M.foldexpr(lnum)
   lnum = lnum or vim.v.lnum
   local bufnr = api.nvim_get_current_buf()
 
-  ---@diagnostic disable-next-line:invisible
   if not vim.treesitter._has_parser(bufnr) or not lnum then
     return '0'
   end

runtime/lua/vim/treesitter/_meta.lua

@@ -3,7 +3,8 @@
 ---@class TSNode
 ---@field id fun(self: TSNode): integer
 ---@field tree fun(self: TSNode): TSTree
----@field range fun(self: TSNode, include_bytes: boolean?): integer, integer, integer, integer, integer, integer
+---@field range fun(self: TSNode, include_bytes: false?): integer, integer, integer, integer
+---@field range fun(self: TSNode, include_bytes: true): integer, integer, integer, integer, integer, integer
 ---@field start fun(self: TSNode): integer, integer, integer
 ---@field end_ fun(self: TSNode): integer, integer, integer
 ---@field type fun(self: TSNode): string

runtime/lua/vim/treesitter/highlighter.lua

@@ -53,12 +53,12 @@ function TSHighlighterQuery.new(lang, query_string)
   return self
 end
 
----@private
+---@package
 function TSHighlighterQuery:query()
   return self._query
 end
 
----@private
+---@package
 ---
 --- Creates a highlighter for `tree`.
 ---
@@ -76,16 +76,14 @@ function TSHighlighter.new(tree, opts)
   opts = opts or {} ---@type { queries: table<string,string> }
   self.tree = tree
   tree:register_cbs({
-    ---@diagnostic disable:invisible
     on_changedtree = function(...)
       self:on_changedtree(...)
     end,
     on_bytes = function(...)
       self:on_bytes(...)
     end,
-    on_detach = function(...)
+    on_detach = function()
-      ---@diagnostic disable-next-line:redundant-parameter
+      self:on_detach()
-      self:on_detach(...)
     end,
   })
 
@@ -147,7 +145,7 @@ function TSHighlighter:destroy()
   end
 end
 
----@private
+---@package
 ---@param tstree TSTree
 ---@return TSHighlightState
 function TSHighlighter:get_highlight_state(tstree)
@@ -166,19 +164,19 @@ function TSHighlighter:reset_highlight_state()
   self._highlight_states = {}
 end
 
----@private
+---@package
 ---@param start_row integer
 ---@param new_end integer
 function TSHighlighter:on_bytes(_, _, start_row, _, _, _, _, _, new_end)
   a.nvim__buf_redraw_range(self.bufnr, start_row, start_row + new_end + 1)
 end
 
----@private
+---@package
 function TSHighlighter:on_detach()
   self:destroy()
 end
 
----@private
+---@package
 ---@param changes integer[][]?
 function TSHighlighter:on_changedtree(changes)
   for _, ch in ipairs(changes or {}) do
@@ -188,7 +186,7 @@ end
 
 --- Gets the query used for @param lang
 --
----@private
+---@package
 ---@param lang string Language used by the highlighter.
 ---@return TSHighlighterQuery
 function TSHighlighter:get_query(lang)
@@ -205,7 +203,6 @@ end
 ---@param line integer
 ---@param is_spell_nav boolean
 local function on_line_impl(self, buf, line, is_spell_nav)
-  ---@diagnostic disable:invisible
   self.tree:for_each_tree(function(tstree, tree)
     if not tstree then
       return
@@ -268,7 +265,7 @@ local function on_line_impl(self, buf, line, is_spell_nav)
         state.next_row = start_row
       end
     end
-  end, true)
+  end)
 end
 
 ---@private

runtime/lua/vim/treesitter/languagetree.lua

@@ -70,7 +70,7 @@ local LanguageTree = {}
 
 LanguageTree.__index = LanguageTree
 
---- @private
+--- @package
 ---
 --- |LanguageTree| contains a tree of parsers: the root treesitter parser for {lang} and any
 --- "injected" language parsers, which themselves may inject other languages, recursively.
@@ -700,7 +700,7 @@ function LanguageTree:_do_callback(cb_name, ...)
   end
 end
 
----@private
+---@package
 function LanguageTree:_edit(
   start_byte,
   end_byte_old,
@@ -776,7 +776,7 @@ function LanguageTree:_edit(
   end)
 end
 
----@private
+---@package
 ---@param bufnr integer
 ---@param changed_tick integer
 ---@param start_row integer
@@ -822,7 +822,6 @@ function LanguageTree:_on_bytes(
   -- Edit trees together BEFORE emitting a bytes callback.
   ---@private
   self:for_each_child(function(child)
-    ---@diagnostic disable-next-line:invisible
     child:_edit(
       start_byte,
       start_byte + old_byte,
@@ -852,12 +851,12 @@ function LanguageTree:_on_bytes(
   )
 end
 
----@private
+---@package
 function LanguageTree:_on_reload()
   self:invalidate(true)
 end
 
----@private
+---@package
 function LanguageTree:_on_detach(...)
   self:invalidate(true)
   self:_do_callback('detach', ...)

runtime/lua/vim/treesitter/playground.lua

@@ -5,11 +5,11 @@ local api = vim.api
 ---@field opts table Options table with the following keys:
 ---                  - anon (boolean): If true, display anonymous nodes
 ---                  - lang (boolean): If true, display the language alongside each node
----@field nodes Node[]
+---@field nodes TSP.Node[]
----@field named Node[]
+---@field named TSP.Node[]
 local TSPlayground = {}
----
+
----@class Node
+---@class TSP.Node
 ---@field id integer Node id
 ---@field text string Node text
 ---@field named boolean True if this is a named (non-anonymous) node
@@ -36,9 +36,9 @@ local TSPlayground = {}
 ---@param node TSNode Starting node to begin traversal |tsnode|
 ---@param depth integer Current recursion depth
 ---@param lang string Language of the tree currently being traversed
----@param injections table<integer,Node> Mapping of node ids to root nodes of injected language trees (see
+---@param injections table<integer,TSP.Node> Mapping of node ids to root nodes of injected language trees (see
 ---                        explanation above)
----@param tree Node[] Output table containing a list of tables each representing a node in the tree
+---@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()]
@@ -87,7 +87,7 @@ end
 ---@return TSPlayground|nil
 ---@return string|nil Error message, if any
 ---
----@private
+---@package
 function TSPlayground:new(bufnr, lang)
   local ok, parser = pcall(vim.treesitter.get_parser, bufnr or 0, lang)
   if not ok then
@@ -114,7 +114,7 @@ function TSPlayground:new(bufnr, lang)
 
   local nodes = traverse(root, 0, parser:lang(), injections, {})
 
-  local named = {} ---@type Node[]
+  local named = {} ---@type TSP.Node[]
   for _, v in ipairs(nodes) do
     if v.named then
       named[#named + 1] = v
@@ -154,7 +154,7 @@ end
 --- Write the contents of this Playground into {bufnr}.
 ---
 ---@param bufnr integer Buffer number to write into.
----@private
+---@package
 function TSPlayground:draw(bufnr)
   vim.bo[bufnr].modifiable = true
   local lines = {} ---@type string[]
@@ -195,8 +195,8 @@ end
 --- The node number is dependent on whether or not anonymous nodes are displayed.
 ---
 ---@param i integer Node number to get
----@return Node
+---@return TSP.Node
----@private
+---@package
 function TSPlayground:get(i)
   local t = self.opts.anon and self.nodes or self.named
   return t[i]
@@ -204,10 +204,10 @@ end
 
 --- Iterate over all of the nodes in this Playground object.
 ---
----@return (fun(): integer, Node) Iterator over all nodes in this Playground
+---@return (fun(): integer, TSP.Node) Iterator over all nodes in this Playground
 ---@return table
 ---@return integer
----@private
+---@package
 function TSPlayground:iter()
   return ipairs(self.opts.anon and self.nodes or self.named)
 end

scripts/lua2dox.lua

@@ -336,6 +336,8 @@ function TLua2DoX_filter.filter(this, AppStamp, Filename)
           offset = 1
         end
 
+        line = line:gsub('@package', '@private')
+
         if vim.startswith(line, '---@cast')
           or vim.startswith(line, '---@diagnostic')
           or vim.startswith(line, '---@type') then