docs(treesitter): expose LanguageTree:parent() #32108

Plugins may want to climb up the LanguageTree.

Also add missing type annotations for other methods.

2 files changed, 20 insertions, 1 deletions

diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 83fa2c5a17..3d76c8c0ff 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -1502,6 +1502,9 @@ analysis on a tree should use a timer to throttle too frequent updates.
 LanguageTree:children()                              *LanguageTree:children()*
     Returns a map of language to child tree.
 
+    Return: ~
+        (`table<string,vim.treesitter.LanguageTree>`)
+
 LanguageTree:contains({range})                       *LanguageTree:contains()*
     Determines whether {range} is contained in the |LanguageTree|.
 
@@ -1566,6 +1569,9 @@ LanguageTree:is_valid({exclude_children})            *LanguageTree:is_valid()*
 LanguageTree:lang()                                      *LanguageTree:lang()*
     Gets the language of this tree node.
 
+    Return: ~
+        (`string`)
+
                                            *LanguageTree:language_for_range()*
 LanguageTree:language_for_range({range})
     Gets the appropriate language that contains {range}.
@@ -1614,6 +1620,12 @@ LanguageTree:node_for_range({range}, {opts})
     Return: ~
         (`TSNode?`)
 
+LanguageTree:parent()                                  *LanguageTree:parent()*
+    Returns the parent tree. `nil` for the root tree.
+
+    Return: ~
+        (`vim.treesitter.LanguageTree?`)
+
 LanguageTree:parse({range}, {on_parse})                 *LanguageTree:parse()*
     Recursively parse all regions in the language tree using
     |treesitter-parsers| for the corresponding languages and run injection
@@ -1674,6 +1686,9 @@ LanguageTree:register_cbs({cbs}, {recursive})
 LanguageTree:source()                                  *LanguageTree:source()*
     Returns the source content of the language tree (bufnr or string).
 
+    Return: ~
+        (`integer|string`)
+
                                                *LanguageTree:tree_for_range()*
 LanguageTree:tree_for_range({range}, {opts})
     Gets the tree that contains {range}.
diff --git a/runtime/lua/vim/treesitter/languagetree.lua b/runtime/lua/vim/treesitter/languagetree.lua
index 35a77f1afc..3db7fe5c9e 100644
--- a/runtime/lua/vim/treesitter/languagetree.lua
+++ b/runtime/lua/vim/treesitter/languagetree.lua
@@ -267,6 +267,7 @@ function LanguageTree:trees()
 end
 
 --- Gets the language of this tree node.
+--- @return string
 function LanguageTree:lang()
   return self._lang
 end
@@ -307,11 +308,13 @@ function LanguageTree:is_valid(exclude_children)
 end
 
 --- Returns a map of language to child tree.
+--- @return table<string,vim.treesitter.LanguageTree>
 function LanguageTree:children()
   return self._children
 end
 
 --- Returns the source content of the language tree (bufnr or string).
+--- @return integer|string
 function LanguageTree:source()
   return self._source
 end
@@ -630,7 +633,8 @@ function LanguageTree:add_child(lang)
   return self._children[lang]
 end
 
---- @package
+---Returns the parent tree. `nil` for the root tree.
+---@return vim.treesitter.LanguageTree?
 function LanguageTree:parent()
   return self._parent
 end