From: Eli Zaretskii <eliz@gnu.org>
Date: Thu, 5 Jan 2023 07:34:02 +0000 (+0200)
Subject: ; Another fix for doc strings of 2 treesit.el functions
X-Git-Tag: emacs-29.0.90~833
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=8a18369afdc3a873881e7b19b75e94ca96791c84;p=emacs.git

; Another fix for doc strings of 2 treesit.el functions

* lisp/treesit.el (treesit-parent-while): Clarify "closest" and
"furthest" in the doc string.  (Bug#60531)
---

diff --git a/lisp/treesit.el b/lisp/treesit.el
index d6822669014..987942c507a 100644
--- a/lisp/treesit.el
+++ b/lisp/treesit.el
@@ -302,9 +302,15 @@ properties."
 (defun treesit-parent-until (node pred &optional include-node)
   "Return the closest parent of NODE that satisfies PRED.
 
-Return nil if none was found.  PRED should be a function that
-takes one argument, the node to examine, and returns a boolean
-value indicating whether that node is a match.
+This function successively examines the parent of NODE, then
+the parent of the parent, etc., until it finds the first
+ancestor node which satisfies the predicate PRED; then it
+returns that ancestor node.  It returns nil if no ancestor
+node was found that satisfies PRED.
+
+PRED should be a function that takes one argument, the node to
+examine, and returns a boolean value indicating whether that
+node is a match.
 
 If INCLUDE-NODE is non-nil, return NODE if it satisfies PRED."
   (let ((node (if include-node node
@@ -315,9 +321,16 @@ If INCLUDE-NODE is non-nil, return NODE if it satisfies PRED."
 
 (defun treesit-parent-while (node pred)
   "Return the furthest parent of NODE that satisfies PRED.
-Return nil if none was found.  PRED should be a function that
-takes one argument, the node to examine, and returns a boolean
-value indicating whether that node is a match."
+
+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.
+
+PRED should be a function that takes one argument, the node to
+examine, and returns a boolean value indicating whether that
+node is a match."
   (let ((last nil))
     (while (and node (funcall pred node))
       (setq last node