[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
emacs-29 8b6a0de964d: Improve docstring of treesit-parent-while (bug#623
From: |
Yuan Fu |
Subject: |
emacs-29 8b6a0de964d: Improve docstring of treesit-parent-while (bug#62301) |
Date: |
Tue, 21 Mar 2023 17:51:49 -0400 (EDT) |
branch: emacs-29
commit 8b6a0de964d61cb8d57ed3fe65086fa305a3c53e
Author: Yuan Fu <casouri@gmail.com>
Commit: Yuan Fu <casouri@gmail.com>
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.
---
doc/lispref/parsing.texi | 22 ++++++++++++++--------
lisp/treesit.el | 12 ++++++------
2 files changed, 20 insertions(+), 14 deletions(-)
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- emacs-29 8b6a0de964d: Improve docstring of treesit-parent-while (bug#62301),
Yuan Fu <=