docs: Treesitter (#13260)

* doc & fixes: Generate treesitter docs

* fixup to treesitter-core

* docs(treesitter): fix docs for most functions

Co-authored-by: Thomas Vigouroux <tomvig38@gmail.com>

1 files changed, 22 insertions, 0 deletions

diff --git a/runtime/lua/vim/treesitter/highlighter.lua b/runtime/lua/vim/treesitter/highlighter.lua
index fe7e1052c9..84b6a5f135 100644
--- a/runtime/lua/vim/treesitter/highlighter.lua
+++ b/runtime/lua/vim/treesitter/highlighter.lua
@@ -70,11 +70,13 @@ TSHighlighter.hl_map = {
     ["include"] = "Include",
 }
 
+---@private
 local function is_highlight_name(capture_name)
   local firstc = string.sub(capture_name, 1, 1)
   return firstc ~= string.lower(firstc)
 end
 
+---@private
 function TSHighlighterQuery.new(lang, query_string)
   local self = setmetatable({}, { __index = TSHighlighterQuery })
 
@@ -99,10 +101,12 @@ function TSHighlighterQuery.new(lang, query_string)
   return self
 end
 
+---@private
 function TSHighlighterQuery:query()
   return self._query
 end
 
+---@private
 --- Get the hl from capture.
 --- Returns a tuple { highlight_name: string, is_builtin: bool }
 function TSHighlighterQuery:_get_hl_from_capture(capture)
@@ -116,6 +120,11 @@ function TSHighlighterQuery:_get_hl_from_capture(capture)
   end
 end
 
+--- Creates a new highlighter using @param tree
+---
+--- @param tree The language tree to use for highlighting
+--- @param opts Table used to configure the highlighter
+---           - queries: Table to overwrite queries used by the highlighter
 function TSHighlighter.new(tree, opts)
   local self = setmetatable({}, TSHighlighter)
 
@@ -165,12 +174,14 @@ function TSHighlighter.new(tree, opts)
   return self
 end
 
+--- Removes all internal references to the highlighter
 function TSHighlighter:destroy()
   if TSHighlighter.active[self.bufnr] then
     TSHighlighter.active[self.bufnr] = nil
   end
 end
 
+---@private
 function TSHighlighter:get_highlight_state(tstree)
   if not self._highlight_states[tstree] then
     self._highlight_states[tstree] = {
@@ -182,24 +193,31 @@ function TSHighlighter:get_highlight_state(tstree)
   return self._highlight_states[tstree]
 end
 
+---@private
 function TSHighlighter:reset_highlight_state()
   self._highlight_states = {}
 end
 
+---@private
 function TSHighlighter:on_bytes(_, _, start_row, _, _, _, _, _, new_end)
   a.nvim__buf_redraw_range(self.bufnr, start_row, start_row + new_end + 1)
 end
 
+---@private
 function TSHighlighter:on_detach()
   self:destroy()
 end
 
+---@private
 function TSHighlighter:on_changedtree(changes)
   for _, ch in ipairs(changes or {}) do
     a.nvim__buf_redraw_range(self.bufnr, ch[1], ch[3]+1)
   end
 end
 
+--- Gets the query used for @param lang
+---
+--- @param lang A language used by the highlighter.
 function TSHighlighter:get_query(lang)
   if not self._queries[lang] then
     self._queries[lang] = TSHighlighterQuery.new(lang)
@@ -208,6 +226,7 @@ function TSHighlighter:get_query(lang)
   return self._queries[lang]
 end
 
+---@private
 local function on_line_impl(self, buf, line)
   self.tree:for_each_tree(function(tstree, tree)
     if not tstree then return end
@@ -251,6 +270,7 @@ local function on_line_impl(self, buf, line)
   end, true)
 end
 
+---@private
 function TSHighlighter._on_line(_, _win, buf, line, _)
   local self = TSHighlighter.active[buf]
   if not self then return end
@@ -258,6 +278,7 @@ function TSHighlighter._on_line(_, _win, buf, line, _)
   on_line_impl(self, buf, line)
 end
 
+---@private
 function TSHighlighter._on_buf(_, buf)
   local self = TSHighlighter.active[buf]
   if self then
@@ -265,6 +286,7 @@ function TSHighlighter._on_buf(_, buf)
   end
 end
 
+---@private
 function TSHighlighter._on_win(_, _win, buf, _topline)
   local self = TSHighlighter.active[buf]
   if not self then