From 85b8ec56a8d4f04058d5a82151ee61a066e32f15 Mon Sep 17 00:00:00 2001
From: Juri Linkov <juri@linkov.net>
Date: Sun, 4 Feb 2024 19:22:21 +0200
Subject: [PATCH] * doc/lispref/parsing.texi (Retrieving Nodes): Improve
 documentation.

Update optional arguments 'predicate' and 'include-node'
of 'treesit-node-top-level'.

(cherry picked from commit 4749699370370a6bf0d50612dafe871dbaf52924)
---
 doc/lispref/parsing.texi  | 34 ++++++++++++++++++----------------
 test/src/treesit-tests.el |  2 +-
 2 files changed, 19 insertions(+), 17 deletions(-)

diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index ac11f88ae4d..d685b7f32dc 100644
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -794,7 +794,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?''
@@ -916,35 +916,37 @@ 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}.  @var{pred} can be either a
-function that takes a node as argument and returns @code{t} or
-@code{nil}, or a regexp matching node type names, or other valid
+the parent that satisfies @var{predicate}.  @var{predicate} can be
+either a function that takes a node as argument and returns @code{t}
+or @code{nil}, or a regexp matching node type names, or other valid
 predicates described in @var{treesit-thing-settings}.  If no parent
-satisfies @var{pred}, this function returns @code{nil}.
+satisfies @var{predicates}, 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}.  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, @var{node} itself is returned.
-
-@var{pred} is the same as in @code{treesit-parent-until} above.
+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{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 a89bf1298c0..bdc9630c783 100644
--- a/test/src/treesit-tests.el
+++ b/test/src/treesit-tests.el
@@ -254,7 +254,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
-- 
2.39.5