From: Yuan Fu <casouri@gmail.com>
Date: Tue, 21 Mar 2023 21:50:07 +0000 (-0700)
Subject: Improve docstring of treesit-parent-while (bug#62301)
X-Git-Tag: emacs-29.0.90~116
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=8b6a0de964d61cb8d57ed3fe65086fa305a3c53e;p=emacs.git

Improve docstring of treesit-parent-while (bug#62301)

* doc/lispref/parsing.texi (Retrieving Nodes): Improve and fix
docstring for treesit-parent-until and treesit-parent-while.
* lisp/treesit.el (treesit-parent-while): Improve docstring.
---

diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index fd65fa3e75b..cba323d3a56 100644
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -859,18 +859,24 @@ return non-@code{nil} to indicate that the node should be kept.  If
 nodes.
 @end defun
 
-@defun treesit-parent-until node predicate
+@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{predicate}, a function that takes a
-node as the argument.  If no parent satisfies @var{predicate}, this
-function returns @code{nil}.
+the parent that satisfies @var{pred}, a function that takes a node as
+the argument and returns a boolean that indicates a match.  If no
+parent satisfies @var{pred}, 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-@var{nil}, this
+function returns @var{node} if @var{node} satisfies @var{pred}.
 @end defun
 
-@defun treesit-parent-while node predicate
-This function repeatedly finds the parent of @var{node}, and keeps
-doing so as long as the nodes satisfy @var{predicate}, a function that
+@defun treesit-parent-while node pred
+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
 takes a node as the argument.  That is, this function returns the
-farthest parent that still satisfies @var{predicate}.
+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.
 @end defun
 
 @defun treesit-node-top-level node &optional type
diff --git a/lisp/treesit.el b/lisp/treesit.el
index b271a1f0c4b..e718ea1a23a 100644
--- a/lisp/treesit.el
+++ b/lisp/treesit.el
@@ -324,13 +324,13 @@ If INCLUDE-NODE is non-nil, return NODE if it satisfies PRED."
     node))
 
 (defun treesit-parent-while (node pred)
-  "Return the furthest parent of NODE that satisfies PRED.
+  "Return the furthest parent of NODE (including NODE) that satisfies PRED.
 
-This function successively examines the parent of NODE, then
-the parent of the parent, etc., until it finds an ancestor node
-which no longer satisfies the predicate PRED; it returns the last
-examined ancestor that satisfies PRED.  It returns nil if no
-ancestor node was found that satisfies PRED.
+This function successively examines NODE, the parent of NODE,
+then the parent of the parent, etc., until it finds a node which
+no longer satisfies the predicate PRED; it returns the last
+examined node that satisfies PRED.  If no node satisfies PRED, it
+returns nil.
 
 PRED should be a function that takes one argument, the node to
 examine, and returns a boolean value indicating whether that