feat(treesitter): introduce child_with_descendant()

This commit also marks `child_containing_descendant()` as deprecated
(per upstream's documentation), and uses `child_with_descendant()` in
its place. Minimum required tree-sitter version will now be `0.24`.

3 files changed, 27 insertions, 12 deletions

diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index 72d2faca02..6895348d05 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -36,6 +36,11 @@ DIAGNOSTICS
 - The "cursor_position" parameter of |vim.diagnostic.JumpOpts| is renamed to
   "pos"
 
+TREESITTER
+• *TSNode:child_containing_descendant()*	Use
+  |TSNode:child_with_descendant()| instead; it is identical except that it can
+  return the descendant itself.
+
 ------------------------------------------------------------------------------
 DEPRECATED IN 0.10					*deprecated-0.10*
 
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 9bc20c3827..1d364ba29a 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -108,6 +108,9 @@ TREESITTER
   if no languages are explicitly registered.
 • |vim.treesitter.language.add()| returns `true` if a parser was loaded
   successfully and `nil,errmsg` otherwise instead of throwing an error.
+• New |TSNode:child_with_descendant()|, which is nearly identical to
+  |TSNode:child_containing_descendant()| except that it can return the
+  descendant itself.
 
 TUI
 
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 35192cc43d..805876172d 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -622,9 +622,23 @@ TSNode:child({index})                                         *TSNode:child()*
     Return: ~
         (`TSNode?`)
 
-                                        *TSNode:child_containing_descendant()*
-TSNode:child_containing_descendant({descendant})
-    Get the node's child that contains {descendant}.
+TSNode:child_count()                                    *TSNode:child_count()*
+    Get the node's number of children.
+
+    Return: ~
+        (`integer`)
+
+                                              *TSNode:child_with_descendant()*
+TSNode:child_with_descendant({descendant})
+    Get the node's child that contains {descendant} (includes {descendant}).
+
+    For example, with the following node hierarchy: >
+        a -> b -> c
+
+        a:child_with_descendant(c) == b
+        a:child_with_descendant(b) == b
+        a:child_with_descendant(a) == nil
+<
 
     Parameters: ~
       • {descendant}  (`TSNode`)
@@ -632,12 +646,6 @@ TSNode:child_containing_descendant({descendant})
     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,
@@ -778,9 +786,8 @@ TSNode:next_sibling()                                  *TSNode:next_sibling()*
         (`TSNode?`)
 
 TSNode:parent()                                              *TSNode:parent()*
-    Get the node's immediate parent. Prefer
-    |TSNode:child_containing_descendant()| for iterating over the node's
-    ancestors.
+    Get the node's immediate parent. Prefer |TSNode:child_with_descendant()|
+    for iterating over the node's ancestors.
 
     Return: ~
         (`TSNode?`)