docs(treesitter): generate TSNode, TSTree docs #30643

**Problem:** The documentation for `TSNode` and `TSTree` methods is
incomplete from the LSP perspective. This is because they are written
directly to the vimdoc, rather than in Lua and generated to vimdoc.

**Solution:** Migrate the docs to Lua and generate them into the vimdoc.
This requires breaking up the `treesitter/_meta.lua` file into a
directory with a few different modules.

This commit also makes the vimdoc generator slightly more robust with
regard to sections that have multiple help tags (e.g. `*one* *two*`)

runtime/doc/treesitter.txt

@@ -57,151 +57,6 @@ loaded: >lua
     vim.treesitter.language.add('python', { path = "/path/to/python.wasm" })
 <
 
-==============================================================================
-TREESITTER TREES                                             *treesitter-tree*
-                                                                      *TSTree*
-
-A "treesitter tree" represents the parsed contents of a buffer, which can be
-used to perform further analysis. It is a |userdata| reference to an object
-held by the treesitter library.
-
-An instance `TSTree` of a treesitter tree supports the following methods.
-
-TSTree:root()                                           *TSTree:root()*
-    Return the root node of this tree.
-
-TSTree:copy()                                           *TSTree:copy()*
-    Returns a copy of the `TSTree`.
-
-==============================================================================
-TREESITTER NODES                                             *treesitter-node*
-                                                                      *TSNode*
-
-A "treesitter node" represents one specific element of the parsed contents of
-a buffer, which can be captured by a |Query| for, e.g., highlighting. It is
-a |userdata| reference to an object held by the treesitter library.
-
-An instance `TSNode` of a treesitter node supports the following methods.
-
-TSNode:parent()                                         *TSNode:parent()*
-    Get the node's immediate parent.
-    Prefer |TSNode:child_containing_descendant()|
-    for iterating over the node's ancestors.
-
-TSNode:next_sibling()                                   *TSNode:next_sibling()*
-    Get the node's next sibling.
-
-TSNode:prev_sibling()                                   *TSNode:prev_sibling()*
-    Get the node's previous sibling.
-
-TSNode:next_named_sibling()                       *TSNode:next_named_sibling()*
-    Get the node's next named sibling.
-
-TSNode:prev_named_sibling()                       *TSNode:prev_named_sibling()*
-    Get the node's previous named sibling.
-
-TSNode:iter_children()                                 *TSNode:iter_children()*
-    Iterates over all the direct children of {TSNode}, regardless of whether
-    they are named or not.
-    Returns the child node plus the eventual field name corresponding to this
-    child node.
-
-TSNode:field({name})                                    *TSNode:field()*
-    Returns a table of the nodes corresponding to the {name} field.
-
-TSNode:child_count()                                    *TSNode:child_count()*
-    Get the node's number of children.
-
-TSNode:child({index})                                   *TSNode:child()*
-    Get the node's child at the given {index}, where zero represents the first
-    child.
-
-TSNode:named_child_count()                         *TSNode:named_child_count()*
-    Get the node's number of named children.
-
-TSNode:named_child({index})                              *TSNode:named_child()*
-    Get the node's named child at the given {index}, where zero represents the
-    first named child.
-
-TSNode:child_containing_descendant({descendant})  *TSNode:child_containing_descendant()*
-    Get the node's child that contains {descendant}.
-
-TSNode:start()                                          *TSNode:start()*
-    Get the node's start position. Return three values: the row, column and
-    total byte count (all zero-based).
-
-TSNode:end_()                                           *TSNode:end_()*
-    Get the node's end position. Return three values: the row, column and
-    total byte count (all zero-based).
-
-TSNode:range({include_bytes})                           *TSNode:range()*
-    Get the range of the node.
-
-    Return four or six values:
-        - start row
-        - start column
-        - start byte (if {include_bytes} is `true`)
-        - end row
-        - end column
-        - end byte (if {include_bytes} is `true`)
-
-TSNode:type()                                           *TSNode:type()*
-    Get the node's type as a string.
-
-TSNode:symbol()                                         *TSNode:symbol()*
-    Get the node's type as a numerical id.
-
-TSNode:named()                                          *TSNode:named()*
-    Check if the node is named. Named nodes correspond to named rules in the
-    grammar, whereas anonymous nodes correspond to string literals in the
-    grammar.
-
-TSNode:missing()                                        *TSNode:missing()*
-    Check if the node is missing. Missing nodes are inserted by the parser in
-    order to recover from certain kinds of syntax errors.
-
-TSNode:extra()                                          *TSNode:extra()*
-    Check if the node is extra. Extra nodes represent things like comments,
-    which are not required by the grammar but can appear anywhere.
-
-TSNode:has_changes()                                    *TSNode:has_changes()*
-    Check if a syntax node has been edited.
-
-TSNode:has_error()                                      *TSNode:has_error()*
-    Check if the node is a syntax error or contains any syntax errors.
-
-TSNode:sexpr()                                          *TSNode:sexpr()*
-    Get an S-expression representing the node as a string.
-
-TSNode:id()                                             *TSNode:id()*
-    Get a unique identifier for the node inside its own tree.
-
-    No guarantees are made about this identifier's internal representation,
-    except for being a primitive Lua type with value equality (so not a
-    table). Presently it is a (non-printable) string.
-
-    Note: The `id` is not guaranteed to be unique for nodes from different
-    trees.
-
-TSNode:tree()                                           *TSNode:tree()*
-    Get the |TSTree| of the node.
-                                                *TSNode:descendant_for_range()*
-TSNode:descendant_for_range({start_row}, {start_col}, {end_row}, {end_col})
-    Get the smallest node within this node that spans the given range of (row,
-    column) positions
-
-                                          *TSNode:named_descendant_for_range()*
-TSNode:named_descendant_for_range({start_row}, {start_col}, {end_row}, {end_col})
-    Get the smallest named node within this node that spans the given range of
-    (row, column) positions
-                                                        *TSNode:equal()*
-TSNode:equal({node})
-    Check if {node} refers to the same node within the same tree.
-
-                                                        *TSNode:byte_length()*
-TSNode:byte_length()
-    Return the number of bytes spanned by this node.
-
 ==============================================================================
 TREESITTER QUERIES                                          *treesitter-query*
 
@@ -718,6 +573,278 @@ library.
 The earliest parser ABI version that is supported by the bundled treesitter
 library.
 
+==============================================================================
+TREESITTER TREES                                    *treesitter-tree* *TSTree*
+
+A "treesitter tree" represents the parsed contents of a buffer, which can be
+used to perform further analysis. It is a |userdata| reference to an object
+held by the treesitter library.
+
+An instance `TSTree` of a treesitter tree supports the following methods.
+
+
+TSTree:copy()                                                  *TSTree:copy()*
+    Returns a copy of the `TSTree`.
+
+    Return: ~
+        (`TSTree`)
+
+TSTree:root()                                                  *TSTree:root()*
+    Return the root node of this tree.
+
+    Return: ~
+        (`TSNode`)
+
+
+==============================================================================
+TREESITTER NODES                                    *treesitter-node* *TSNode*
+
+A "treesitter node" represents one specific element of the parsed contents of
+a buffer, which can be captured by a |Query| for, e.g., highlighting. It is a
+|userdata| reference to an object held by the treesitter library.
+
+An instance `TSNode` of a treesitter node supports the following methods.
+
+
+TSNode:byte_length()                                    *TSNode:byte_length()*
+    Return the number of bytes spanned by this node.
+
+    Return: ~
+        (`integer`)
+
+TSNode:child({index})                                         *TSNode:child()*
+    Get the node's child at the given {index}, where zero represents the first
+    child.
+
+    Parameters: ~
+      • {index}  (`integer`)
+
+    Return: ~
+        (`TSNode?`)
+
+                                        *TSNode:child_containing_descendant()*
+TSNode:child_containing_descendant({descendant})
+    Get the node's child that contains {descendant}.
+
+    Parameters: ~
+      • {descendant}  (`TSNode`)
+
+    Return: ~
+        (`TSNode?`)
+
+TSNode:child_count()                                    *TSNode:child_count()*
+    Get the node's number of children.
+
+    Return: ~
+        (`integer`)
+
+                                               *TSNode:descendant_for_range()*
+TSNode:descendant_for_range({start_row}, {start_col}, {end_row}, {end_col})
+    Get the smallest node within this node that spans the given range of (row,
+    column) positions
+
+    Parameters: ~
+      • {start_row}  (`integer`)
+      • {start_col}  (`integer`)
+      • {end_row}    (`integer`)
+      • {end_col}    (`integer`)
+
+    Return: ~
+        (`TSNode?`)
+
+TSNode:end_()                                                  *TSNode:end_()*
+    Get the node's end position. Return three values: the row, column and
+    total byte count (all zero-based).
+
+    Return (multiple): ~
+        (`integer`)
+        (`integer`)
+        (`integer`)
+
+TSNode:equal({node})                                          *TSNode:equal()*
+    Check if {node} refers to the same node within the same tree.
+
+    Parameters: ~
+      • {node}  (`TSNode`)
+
+    Return: ~
+        (`boolean`)
+
+TSNode:extra()                                                *TSNode:extra()*
+    Check if the node is extra. Extra nodes represent things like comments,
+    which are not required by the grammar but can appear anywhere.
+
+    Return: ~
+        (`boolean`)
+
+TSNode:field({name})                                          *TSNode:field()*
+    Returns a table of the nodes corresponding to the {name} field.
+
+    Parameters: ~
+      • {name}  (`string`)
+
+    Return: ~
+        (`TSNode[]`)
+
+TSNode:has_changes()                                    *TSNode:has_changes()*
+    Check if a syntax node has been edited.
+
+    Return: ~
+        (`boolean`)
+
+TSNode:has_error()                                        *TSNode:has_error()*
+    Check if the node is a syntax error or contains any syntax errors.
+
+    Return: ~
+        (`boolean`)
+
+TSNode:id()                                                      *TSNode:id()*
+    Get a unique identifier for the node inside its own tree.
+
+    No guarantees are made about this identifier's internal representation,
+    except for being a primitive Lua type with value equality (so not a
+    table). Presently it is a (non-printable) string.
+
+    Note: The `id` is not guaranteed to be unique for nodes from different
+    trees.
+
+    Return: ~
+        (`string`)
+
+TSNode:iter_children()                                *TSNode:iter_children()*
+    Iterates over all the direct children of {TSNode}, regardless of whether
+    they are named or not. Returns the child node plus the eventual field name
+    corresponding to this child node.
+
+    Return: ~
+        (`fun(): TSNode, string`)
+
+TSNode:missing()                                            *TSNode:missing()*
+    Check if the node is missing. Missing nodes are inserted by the parser in
+    order to recover from certain kinds of syntax errors.
+
+    Return: ~
+        (`boolean`)
+
+TSNode:named()                                                *TSNode:named()*
+    Check if the node is named. Named nodes correspond to named rules in the
+    grammar, whereas anonymous nodes correspond to string literals in the
+    grammar.
+
+    Return: ~
+        (`boolean`)
+
+TSNode:named_child({index})                             *TSNode:named_child()*
+    Get the node's named child at the given {index}, where zero represents the
+    first named child.
+
+    Parameters: ~
+      • {index}  (`integer`)
+
+    Return: ~
+        (`TSNode?`)
+
+TSNode:named_child_count()                        *TSNode:named_child_count()*
+    Get the node's number of named children.
+
+    Return: ~
+        (`integer`)
+
+                                         *TSNode:named_descendant_for_range()*
+TSNode:named_descendant_for_range({start_row}, {start_col}, {end_row},
+                                  {end_col})
+    Get the smallest named node within this node that spans the given range of
+    (row, column) positions
+
+    Parameters: ~
+      • {start_row}  (`integer`)
+      • {start_col}  (`integer`)
+      • {end_row}    (`integer`)
+      • {end_col}    (`integer`)
+
+    Return: ~
+        (`TSNode?`)
+
+TSNode:next_named_sibling()                      *TSNode:next_named_sibling()*
+    Get the node's next named sibling.
+
+    Return: ~
+        (`TSNode?`)
+
+TSNode:next_sibling()                                  *TSNode:next_sibling()*
+    Get the node's next sibling.
+
+    Return: ~
+        (`TSNode?`)
+
+TSNode:parent()                                              *TSNode:parent()*
+    Get the node's immediate parent. Prefer
+    |TSNode:child_containing_descendant()| for iterating over the node's
+    ancestors.
+
+    Return: ~
+        (`TSNode?`)
+
+TSNode:prev_named_sibling()                      *TSNode:prev_named_sibling()*
+    Get the node's previous named sibling.
+
+    Return: ~
+        (`TSNode?`)
+
+TSNode:prev_sibling()                                  *TSNode:prev_sibling()*
+    Get the node's previous sibling.
+
+    Return: ~
+        (`TSNode?`)
+
+TSNode:range({include_bytes})                                 *TSNode:range()*
+    Get the range of the node.
+
+    Return four or six values:
+    • start row
+    • start column
+    • start byte (if {include_bytes} is `true`)
+    • end row
+    • end column
+    • end byte (if {include_bytes} is `true`)
+
+    Parameters: ~
+      • {include_bytes}  (`boolean?`)
+
+TSNode:sexpr()                                                *TSNode:sexpr()*
+    Get an S-expression representing the node as a string.
+
+    Return: ~
+        (`string`)
+
+TSNode:start()                                                *TSNode:start()*
+    Get the node's start position. Return three values: the row, column and
+    total byte count (all zero-based).
+
+    Return (multiple): ~
+        (`integer`)
+        (`integer`)
+        (`integer`)
+
+TSNode:symbol()                                              *TSNode:symbol()*
+    Get the node's type as a numerical id.
+
+    Return: ~
+        (`integer`)
+
+TSNode:tree()                                                  *TSNode:tree()*
+    Get the |TSTree| of the node.
+
+    Return: ~
+        (`TSTree`)
+
+TSNode:type()                                                  *TSNode:type()*
+    Get the node's type as a string.
+
+    Return: ~
+        (`string`)
+
+
 ==============================================================================
 Lua module: vim.treesitter                               *lua-treesitter-core*
 

runtime/lua/vim/treesitter/_meta.lua

@@ -1,119 +0,0 @@
----@meta
-error('Cannot require a meta file')
-
----@class TSNode: userdata
----@field id fun(self: TSNode): string
----@field tree fun(self: TSNode): TSTree
----@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
----@field symbol fun(self: TSNode): integer
----@field named fun(self: TSNode): boolean
----@field missing fun(self: TSNode): boolean
----@field extra fun(self: TSNode): boolean
----@field child_count fun(self: TSNode): integer
----@field named_child_count fun(self: TSNode): integer
----@field child fun(self: TSNode, index: integer): TSNode?
----@field named_child fun(self: TSNode, index: integer): TSNode?
----@field descendant_for_range fun(self: TSNode, start_row: integer, start_col: integer, end_row: integer, end_col: integer): TSNode?
----@field named_descendant_for_range fun(self: TSNode, start_row: integer, start_col: integer, end_row: integer, end_col: integer): TSNode?
----@field parent fun(self: TSNode): TSNode?
----@field child_containing_descendant fun(self: TSNode, descendant: TSNode): TSNode?
----@field next_sibling fun(self: TSNode): TSNode?
----@field prev_sibling fun(self: TSNode): TSNode?
----@field next_named_sibling fun(self: TSNode): TSNode?
----@field prev_named_sibling fun(self: TSNode): TSNode?
----@field named_children fun(self: TSNode): TSNode[]
----@field has_changes fun(self: TSNode): boolean
----@field has_error fun(self: TSNode): boolean
----@field sexpr fun(self: TSNode): string
----@field equal fun(self: TSNode, other: TSNode): boolean
----@field iter_children fun(self: TSNode): fun(): TSNode, string
----@field field fun(self: TSNode, name: string): TSNode[]
----@field byte_length fun(self: TSNode): integer
----@field __has_ancestor fun(self: TSNode, node_types: string[]): boolean
-local TSNode = {}
-
----@alias TSLoggerCallback fun(logtype: 'parse'|'lex', msg: string)
-
----@class TSParser: userdata
----@field parse fun(self: TSParser, tree: TSTree?, source: integer|string, include_bytes: boolean): TSTree, (Range4|Range6)[]
----@field reset fun(self: TSParser)
----@field included_ranges fun(self: TSParser, include_bytes: boolean?): integer[]
----@field set_included_ranges fun(self: TSParser, ranges: (Range6|TSNode)[])
----@field set_timeout fun(self: TSParser, timeout: integer)
----@field timeout fun(self: TSParser): integer
----@field _set_logger fun(self: TSParser, lex: boolean, parse: boolean, cb: TSLoggerCallback)
----@field _logger fun(self: TSParser): TSLoggerCallback
-
----@class TSTree: userdata
----@field root fun(self: TSTree): TSNode
----@field edit fun(self: TSTree, _: integer, _: integer, _: integer, _: integer, _: integer, _: integer, _: integer, _: integer, _:integer)
----@field copy fun(self: TSTree): TSTree
----@field included_ranges fun(self: TSTree, include_bytes: true): Range6[]
----@field included_ranges fun(self: TSTree, include_bytes: false): Range4[]
-
----@class TSQuery: userdata
----@field inspect fun(self: TSQuery): TSQueryInfo
-
----@class (exact) TSQueryInfo
----@field captures string[]
----@field patterns table<integer, (integer|string)[][]>
-
---- @param lang string
---- @return table
-vim._ts_inspect_language = function(lang) end
-
----@return integer
-vim._ts_get_language_version = function() end
-
---- @param path string
---- @param lang string
---- @param symbol_name? string
-vim._ts_add_language_from_object = function(path, lang, symbol_name) end
-
---- @param path string
---- @param lang string
-vim._ts_add_language_from_wasm = function(path, lang) end
-
----@return integer
-vim._ts_get_minimum_language_version = function() end
-
----@param lang string Language to use for the query
----@param query string Query string in s-expr syntax
----@return TSQuery
-vim._ts_parse_query = function(lang, query) end
-
----@param lang string
----@return TSParser
-vim._create_ts_parser = function(lang) end
-
---- @class TSQueryMatch: userdata
---- @field captures fun(self: TSQueryMatch): table<integer,TSNode[]>
-local TSQueryMatch = {}
-
---- @return integer match_id
---- @return integer pattern_index
-function TSQueryMatch:info() end
-
---- @class TSQueryCursor: userdata
---- @field remove_match fun(self: TSQueryCursor, id: integer)
-local TSQueryCursor = {}
-
---- @return integer capture
---- @return TSNode captured_node
---- @return TSQueryMatch match
-function TSQueryCursor:next_capture() end
-
---- @return TSQueryMatch match
-function TSQueryCursor:next_match() end
-
---- @param node TSNode
---- @param query TSQuery
---- @param start integer?
---- @param stop integer?
---- @param opts? { max_start_depth?: integer, match_limit?: integer}
---- @return TSQueryCursor
-function vim._create_ts_querycursor(node, query, start, stop, opts) end

runtime/lua/vim/treesitter/_meta/misc.lua

@@ -0,0 +1,78 @@
+---@meta
+-- luacheck: no unused args
+error('Cannot require a meta file')
+
+---@alias TSLoggerCallback fun(logtype: 'parse'|'lex', msg: string)
+
+---@class TSParser: userdata
+---@field parse fun(self: TSParser, tree: TSTree?, source: integer|string, include_bytes: boolean): TSTree, (Range4|Range6)[]
+---@field reset fun(self: TSParser)
+---@field included_ranges fun(self: TSParser, include_bytes: boolean?): integer[]
+---@field set_included_ranges fun(self: TSParser, ranges: (Range6|TSNode)[])
+---@field set_timeout fun(self: TSParser, timeout: integer)
+---@field timeout fun(self: TSParser): integer
+---@field _set_logger fun(self: TSParser, lex: boolean, parse: boolean, cb: TSLoggerCallback)
+---@field _logger fun(self: TSParser): TSLoggerCallback
+
+---@class TSQuery: userdata
+---@field inspect fun(self: TSQuery): TSQueryInfo
+
+---@class (exact) TSQueryInfo
+---@field captures string[]
+---@field patterns table<integer, (integer|string)[][]>
+
+--- @param lang string
+--- @return table
+vim._ts_inspect_language = function(lang) end
+
+---@return integer
+vim._ts_get_language_version = function() end
+
+--- @param path string
+--- @param lang string
+--- @param symbol_name? string
+vim._ts_add_language_from_object = function(path, lang, symbol_name) end
+
+--- @param path string
+--- @param lang string
+vim._ts_add_language_from_wasm = function(path, lang) end
+
+---@return integer
+vim._ts_get_minimum_language_version = function() end
+
+---@param lang string Language to use for the query
+---@param query string Query string in s-expr syntax
+---@return TSQuery
+vim._ts_parse_query = function(lang, query) end
+
+---@param lang string
+---@return TSParser
+vim._create_ts_parser = function(lang) end
+
+--- @class TSQueryMatch: userdata
+--- @field captures fun(self: TSQueryMatch): table<integer,TSNode[]>
+local TSQueryMatch = {} -- luacheck: no unused
+
+--- @return integer match_id
+--- @return integer pattern_index
+function TSQueryMatch:info() end
+
+--- @class TSQueryCursor: userdata
+--- @field remove_match fun(self: TSQueryCursor, id: integer)
+local TSQueryCursor = {} -- luacheck: no unused
+
+--- @return integer capture
+--- @return TSNode captured_node
+--- @return TSQueryMatch match
+function TSQueryCursor:next_capture() end
+
+--- @return TSQueryMatch match
+function TSQueryCursor:next_match() end
+
+--- @param node TSNode
+--- @param query TSQuery
+--- @param start integer?
+--- @param stop integer?
+--- @param opts? { max_start_depth?: integer, match_limit?: integer}
+--- @return TSQueryCursor
+function vim._create_ts_querycursor(node, query, start, stop, opts) end

runtime/lua/vim/treesitter/_meta/tsnode.lua

@@ -0,0 +1,185 @@
+---@meta
+-- luacheck: no unused args
+error('Cannot require a meta file')
+
+--- @brief A "treesitter node" represents one specific element of the parsed contents of a buffer,
+--- which can be captured by a |Query| for, e.g., highlighting. It is a |userdata| reference to an
+--- object held by the treesitter library.
+---
+--- An instance `TSNode` of a treesitter node supports the following methods.
+
+---@nodoc
+---@class TSNode: userdata
+---@field named_children fun(self: TSNode): TSNode[]
+---@field __has_ancestor fun(self: TSNode, node_types: string[]): boolean
+local TSNode = {} -- luacheck: no unused
+
+--- Get the node's immediate parent.
+--- Prefer |TSNode:child_containing_descendant()|
+--- for iterating over the node's ancestors.
+--- @return TSNode?
+function TSNode:parent() end
+
+--- Get the node's next sibling.
+--- @return TSNode?
+function TSNode:next_sibling() end
+
+--- Get the node's previous sibling.
+--- @return TSNode?
+function TSNode:prev_sibling() end
+
+--- Get the node's next named sibling.
+--- @return TSNode?
+function TSNode:next_named_sibling() end
+
+--- Get the node's previous named sibling.
+--- @return TSNode?
+function TSNode:prev_named_sibling() end
+
+--- Iterates over all the direct children of {TSNode}, regardless of whether
+--- they are named or not.
+--- Returns the child node plus the eventual field name corresponding to this
+--- child node.
+--- @return fun(): TSNode, string
+function TSNode:iter_children() end
+
+--- Returns a table of the nodes corresponding to the {name} field.
+--- @param name string
+--- @return TSNode[]
+function TSNode:field(name) end
+
+--- Get the node's number of children.
+--- @return integer
+function TSNode:child_count() end
+
+--- Get the node's child at the given {index}, where zero represents the first
+--- child.
+--- @param index integer
+--- @return TSNode?
+function TSNode:child(index) end
+
+--- Get the node's number of named children.
+--- @return integer
+function TSNode:named_child_count() end
+
+--- Get the node's named child at the given {index}, where zero represents the
+--- first named child.
+--- @param index integer
+--- @return TSNode?
+function TSNode:named_child(index) end
+
+--- Get the node's child that contains {descendant}.
+--- @param descendant TSNode
+--- @return TSNode?
+function TSNode:child_containing_descendant(descendant) end
+
+--- Get the node's start position. Return three values: the row, column and
+--- total byte count (all zero-based).
+--- @return integer, integer, integer
+function TSNode:start() end
+
+--- Get the node's end position. Return three values: the row, column and
+--- total byte count (all zero-based).
+--- @return integer, integer, integer
+function TSNode:end_() end
+
+--- Get the range of the node.
+---
+--- Return four or six values:
+---
+--- - start row
+--- - start column
+--- - start byte (if {include_bytes} is `true`)
+--- - end row
+--- - end column
+--- - end byte (if {include_bytes} is `true`)
+--- @param include_bytes boolean?
+function TSNode:range(include_bytes) end
+
+--- @nodoc
+--- @param include_bytes false?
+--- @return integer, integer, integer, integer
+function TSNode:range(include_bytes) end
+
+--- @nodoc
+--- @param include_bytes true
+--- @return integer, integer, integer, integer, integer, integer
+function TSNode:range(include_bytes) end
+
+--- Get the node's type as a string.
+--- @return string
+function TSNode:type() end
+
+--- Get the node's type as a numerical id.
+--- @return integer
+function TSNode:symbol() end
+
+--- Check if the node is named. Named nodes correspond to named rules in the
+--- grammar, whereas anonymous nodes correspond to string literals in the
+--- grammar.
+--- @return boolean
+function TSNode:named() end
+
+--- Check if the node is missing. Missing nodes are inserted by the parser in
+--- order to recover from certain kinds of syntax errors.
+--- @return boolean
+function TSNode:missing() end
+
+--- Check if the node is extra. Extra nodes represent things like comments,
+--- which are not required by the grammar but can appear anywhere.
+--- @return boolean
+function TSNode:extra() end
+
+--- Check if a syntax node has been edited.
+--- @return boolean
+function TSNode:has_changes() end
+
+--- Check if the node is a syntax error or contains any syntax errors.
+--- @return boolean
+function TSNode:has_error() end
+
+--- Get an S-expression representing the node as a string.
+--- @return string
+function TSNode:sexpr() end
+
+--- Get a unique identifier for the node inside its own tree.
+---
+--- No guarantees are made about this identifier's internal representation,
+--- except for being a primitive Lua type with value equality (so not a
+--- table). Presently it is a (non-printable) string.
+---
+--- Note: The `id` is not guaranteed to be unique for nodes from different
+--- trees.
+--- @return string
+function TSNode:id() end
+
+--- Get the |TSTree| of the node.
+--- @return TSTree
+function TSNode:tree() end
+
+--- Get the smallest node within this node that spans the given range of (row,
+--- column) positions
+--- @param start_row integer
+--- @param start_col integer
+--- @param end_row integer
+--- @param end_col integer
+--- @return TSNode?
+function TSNode:descendant_for_range(start_row, start_col, end_row, end_col) end
+
+--- Get the smallest named node within this node that spans the given range of
+--- (row, column) positions
+--- @param start_row integer
+--- @param start_col integer
+--- @param end_row integer
+--- @param end_col integer
+--- @return TSNode?
+function TSNode:named_descendant_for_range(start_row, start_col, end_row, end_col) end
+
+--- Check if {node} refers to the same node within the same tree.
+--- @param node TSNode
+--- @return boolean
+function TSNode:equal(node) end
+
+--- Return the number of bytes spanned by this node.
+--- @return integer
+function TSNode:byte_length() end

runtime/lua/vim/treesitter/_meta/tstree.lua

@@ -0,0 +1,44 @@
+---@meta
+-- luacheck: no unused args
+error('Cannot require a meta file')
+
+--- @brief A "treesitter tree" represents the parsed contents of a buffer, which can be
+--- used to perform further analysis. It is a |userdata| reference to an object
+--- held by the treesitter library.
+---
+--- An instance `TSTree` of a treesitter tree supports the following methods.
+
+---@nodoc
+---@class TSTree: userdata
+local TSTree = {} -- luacheck: no unused
+
+--- Return the root node of this tree.
+---@return TSNode
+function TSTree:root() end
+
+-- stylua: ignore
+---@param start_byte integer
+---@param end_byte_old integer
+---@param end_byte_new integer
+---@param start_row integer
+---@param start_col integer
+---@param end_row_old integer
+---@param end_col_old integer
+---@param end_row_new integer
+---@param end_col_new integer
+---@nodoc
+function TSTree:edit(start_byte, end_byte_old, end_byte_new, start_row, start_col, end_row_old, end_col_old, end_row_new, end_col_new) end
+
+--- Returns a copy of the `TSTree`.
+---@return TSTree
+function TSTree:copy() end
+
+---@param include_bytes true
+---@return Range6[]
+---@nodoc
+function TSTree:included_ranges(include_bytes) end
+
+---@param include_bytes false
+---@return Range4[]
+---@nodoc
+function TSTree:included_ranges(include_bytes) end

scripts/gen_vimdoc.lua

@@ -50,7 +50,7 @@ local INDENTATION = 4
 --- For generated section names.
 --- @field section_fmt fun(name: string): string
 ---
---- @field helptag_fmt fun(name: string): string
+--- @field helptag_fmt fun(name: string): string|string[]
 ---
 --- Per-function helptag.
 --- @field fn_helptag_fmt? fun(fun: nvim.luacats.parser.fun): string
@@ -319,6 +319,8 @@ local config = {
   treesitter = {
     filename = 'treesitter.txt',
     section_order = {
+      'tstree.lua',
+      'tsnode.lua',
       'treesitter.lua',
       'language.lua',
       'query.lua',
@@ -327,18 +329,27 @@ local config = {
       'dev.lua',
     },
     files = {
+      'runtime/lua/vim/treesitter/_meta/',
       'runtime/lua/vim/treesitter.lua',
       'runtime/lua/vim/treesitter/',
     },
     section_fmt = function(name)
       if name:lower() == 'treesitter' then
         return 'Lua module: vim.treesitter'
+      elseif name:lower() == 'tstree' then
+        return 'TREESITTER TREES'
+      elseif name:lower() == 'tsnode' then
+        return 'TREESITTER NODES'
       end
       return 'Lua module: vim.treesitter.' .. name:lower()
     end,
     helptag_fmt = function(name)
       if name:lower() == 'treesitter' then
         return 'lua-treesitter-core'
+      elseif name:lower() == 'tstree' then
+        return { 'treesitter-tree', 'TSTree' }
+      elseif name:lower() == 'tsnode' then
+        return { 'treesitter-node', 'TSNode' }
       end
       return 'lua-treesitter-' .. name:lower()
     end,
@@ -374,7 +385,7 @@ local config = {
       return 'Checkhealth'
     end,
     helptag_fmt = function()
-      return 'vim.health* *health' -- HACK
+      return { 'vim.health', 'health' }
     end,
   },
 }
@@ -869,7 +880,11 @@ local function make_section(filename, cfg, section_docs, funs_txt)
   local sectname = cfg.section_name and cfg.section_name[filename] or mktitle(name)
 
   -- section tag: e.g., "*api-autocmd*"
-  local help_tag = '*' .. cfg.helptag_fmt(sectname) .. '*'
+  local help_labels = cfg.helptag_fmt(sectname)
+  if type(help_labels) == 'table' then
+    help_labels = table.concat(help_labels, '* *')
+  end
+  local help_tags = '*' .. help_labels .. '*'
 
   if funs_txt == '' and #section_docs == 0 then
     return
@@ -878,7 +893,7 @@ local function make_section(filename, cfg, section_docs, funs_txt)
   return {
     name = sectname,
     title = cfg.section_fmt(sectname),
-    help_tag = help_tag,
+    help_tag = help_tags,
     funs_txt = funs_txt,
     doc = section_docs,
   }