emacs-29 47496993703: * doc/lispref/parsing.texi (Retrieving Nodes): Improve documentation.

[Juri Linkov]

branch: emacs-29
commit 4749699370370a6bf0d50612dafe871dbaf52924
Author: Juri Linkov <juri@linkov.net>
Commit: Juri Linkov <juri@linkov.net>

    * doc/lispref/parsing.texi (Retrieving Nodes): Improve documentation.
    
    Update optional arguments 'predicate' and 'include-node'
    of 'treesit-node-top-level'.
---
 doc/lispref/parsing.texi  | 25 ++++++++++++++-----------
 test/src/treesit-tests.el |  2 +-
 2 files changed, 15 insertions(+), 12 deletions(-)

diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index 26204164243..fbd739b76d5 100644
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -785,7 +785,7 @@ that comes after it in the buffer position order, i.e., 
nodes with
 start positions greater than the end position of @var{start}.
 
 In the tree shown above, @code{treesit-search-subtree} traverses node
-@samp{S} (@var{start}) and nodes marked with @code{o}, where this
+@samp{S} (@var{start}) and nodes marked with @code{o}, whereas this
 function traverses the nodes marked with numbers.  This function is
 useful for answering questions like ``what is the first node after
 @var{start} in the buffer that satisfies some condition?''
@@ -860,32 +860,35 @@ nodes.
 
 @defun treesit-parent-until node predicate &optional include-node
 This function repeatedly finds the parents of @var{node}, and returns
-the parent that satisfies @var{pred}, a function that takes a node as
+the parent that satisfies @var{predicate}, a function that takes a node as
 argument and returns a boolean that indicates a match.  If no parent
-satisfies @var{pred}, this function returns @code{nil}.
+satisfies @var{predicate}, this function returns @code{nil}.
 
 Normally this function only looks at the parents of @var{node} but not
 @var{node} itself.  But if @var{include-node} is non-@code{nil}, this
-function returns @var{node} if @var{node} satisfies @var{pred}.
+function returns @var{node} if @var{node} satisfies @var{predicate}.
 @end defun
 
-@defun treesit-parent-while node pred
+@defun treesit-parent-while node predicate
 This function goes up the tree starting from @var{node}, and keeps
-doing so as long as the nodes satisfy @var{pred}, a function that
+doing so as long as the nodes satisfy @var{predicate}, a function that
 takes a node as argument.  That is, this function returns the highest
-parent of @var{node} that still satisfies @var{pred}.  Note that if
-@var{node} satisfies @var{pred} but its immediate parent doesn't,
+parent of @var{node} that still satisfies @var{predicate}.  Note that if
+@var{node} satisfies @var{predicate} but its immediate parent doesn't,
 @var{node} itself is returned.
 @end defun
 
-@defun treesit-node-top-level node &optional type
+@defun treesit-node-top-level node &optional predicate include-node
 This function returns the highest parent of @var{node} that has the
 same type as @var{node}.  If no such parent exists, it returns
 @code{nil}.  Therefore this function is also useful for testing
 whether @var{node} is top-level.
 
-If @var{type} is non-@code{nil}, this function matches each parent's
-type with @var{type} as a regexp, rather than using @var{node}'s type.
+If @var{predicate} is @code{nil}, this function uses @var{node}'s type
+to find the parent.  If @var{predicate} is non-@code{nil}, this
+function searches the parent that satisfies @var{predicate}.  If
+@var{include-node} is non-@code{nil}, this function returns @var{node}
+if @var{node} satisfies @var{predicate}.
 @end defun
 
 @node Accessing Node Information
diff --git a/test/src/treesit-tests.el b/test/src/treesit-tests.el
index 1cd783bd05e..3eda6fd3c53 100644
--- a/test/src/treesit-tests.el
+++ b/test/src/treesit-tests.el
@@ -243,7 +243,7 @@
         (should (eq nil (treesit-node-text
                          (treesit-search-subtree
                           subarray "\\["))))
-        ;; If ALL=nil, searching for number should still find the
+        ;; If ALL=t, searching for number should still find the
         ;; numbers.
         (should (equal "1" (treesit-node-text
                             (treesit-search-subtree