feature/tree-sitter 316bdc334c 15/26: Add manual for treesit-traverse-forward and friends

[Yuan Fu]

branch: feature/tree-sitter
commit 316bdc334ca4f3b7101ac6879e84041646852488
Author: Yuan Fu <casouri@gmail.com>
Commit: Yuan Fu <casouri@gmail.com>

    Add manual for treesit-traverse-forward and friends
    
    * doc/lispref/parsing.texi (Retrieving Node): Add manual entry for
    treesit-traverse-depth-first, treesit-traverse-breadth-first,
    treesit-traverse-forward.
    * lisp/treesit.el (treesit-traverse-forward): Fix docstring.
---
 doc/lispref/parsing.texi | 67 ++++++++++++++++++++++++++++++++++++++++++++++++
 lisp/treesit.el          | 15 ++++++-----
 2 files changed, 75 insertions(+), 7 deletions(-)

diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index 72be91877b..cadddf0c00 100644
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -630,6 +630,73 @@ parent as the single argument).  I.e., this function 
returns the
 farthest parent that still satisfies @var{pred}.
 @end defun
 
+@cindex trees-sitter tree traversal
+@defun treesit-traverse-depth-first node pred &optional step depth
+Traverse the subtree of @var{node} depth-first. Traverse starting from
+@var{node} (i.e., @var{node} is passed to @var{pred}).  For each node
+traversed, we call @var{pred} with the node, and we stop and return
+the node if @var{pred} returns non-nil.  If no node satisfies
+@var{pred}, return nil.
+
+If @var{step} >= 0 or nil, go forward, if @var{step} < 0, go backward.
+(The quantity of @var{step} doesn't matter.)
+
+@var{depth} can be a positive integer or 0, meaning go @var{depth}
+levels deep, counting from @var{node}, or nil, meaning there is no
+limit.  For example, a value 0 means only traverse @var{node} itself,
+a value 1 means traverse @var{node} and its immediate children.
+@end defun
+
+@defun treesit-traverse-breadth-first node pred &optional step
+Traverse the subtree of @var{node} breadth-first.  Traverse starting
+from @var{node} (i.e., @var{node} is passed to @var{pred}).  For each
+node traversed, call @var{pred} with the node, stop and return the
+node if @var{pred} returns non-nil.  If no node satisfies @var{pred},
+return nil.
+
+If @var{step} >= 0 or nil, go forward, if @var{step} < 0, go backward.
+(The quantity of @var{step} doesn't matter.)
+@end defun
+
+@defun treesit-traverse-forward node pred &optional step depth
+Traverses the whole tree forward from NODE depth-first.  Traverse
+starting from @var{node} (i.e., @var{node} is passed to @var{pred}).
+For each node traversed, call @var{pred} with the node, stop and
+return the node if @var{pred} returns non-nil.  If no node satisfies
+@var{pred}, return nil.
+
+If @var{step} >= 0 or nil, go forward, if @var{step} < 0, go backward.
+(The quantity of @var{step} doesn't matter.)
+
+Traversing forward means that for a tree like the below where
+@var{node} is marked 1, traverse as numbered:
+
+@example
+@group
+                16
+                |
+       3--------4-----------8
+       |        |           |
+  o--o-+--1  5--+--6    9---+-----12
+  |  |    |        |    |         |
+  o  o    2        7  +-+-+    +--+--+
+                      |   |    |  |  |
+                      10  11   13 14 15
+@end group
+@end example
+
+@var{depth} can be a positive integer, 0, nil, or @code{'up}.  A
+positive integer or 0 means go @var{depth} deep counting from
+@var{node}.  A nil means no limit.  And a symbol @code{'up} means go
+upwards only: only traverse to sibling and parent, never go down to
+children.
+
+The difference between 0 and @code{'up} is subtle: in the above
+example, if given 0 as @var{depth}, node 1 3 4 5 6 8 9 12 16 are
+visited; if given @code{'up} as @var{depth}, only node 1 3 4 8 16 are
+visited.
+@end defun
+
 @node Accessing Node
 @section Accessing Node Information
 
diff --git a/lisp/treesit.el b/lisp/treesit.el
index d6d092ee6a..4e35a46650 100644
--- a/lisp/treesit.el
+++ b/lisp/treesit.el
@@ -311,8 +311,8 @@ node if PRED returns non-nil.  If STEP >= 0 or nil, go 
forward,
 if STEP < 0, go backward.  If no node satisfies PRED, return
 nil.
 
-Traversing forward depth-first means, for a tree like the below
-where NODE is marked 1, traverse as numbered:
+Traversing forward depth-first means that for a tree like the
+below where NODE is marked 1, traverse as numbered:
 
                 16
                 |
@@ -326,11 +326,12 @@ where NODE is marked 1, traverse as numbered:
 
 DEPTH can be a positive integer, 0, nil, or 'up.  A positive
 integer or 0 means go DEPTH deep counting from NODE.  A nil means
-no limit.  And a symbol 'up means upward only: only traverse
-sibling and parent, never go down.  The difference between 0 and
-'up is subtle: in the above example, if given 0 as DEPTH, node 1
-3 4 5 6 8 9 12 16 are visited; if given t as DEPTH, only node 1 3
-4 8 16 are visited."
+no limit.  And a symbol 'up means go upwards only: only traverse
+sibling and parent, never go down to children.
+
+The difference between 0 and 'up is subtle: in the above example,
+if given 0 as DEPTH, node 1 3 4 5 6 8 9 12 16 are visited; if
+given 'up as DEPTH, only node 1 3 4 8 16 are visited."
   ;; First try NODE's subtree, but only under these conditions: if
   ;; DEPTH is a number, it has to be greater than 0, if it's a symbol,
   ;; it cannot be 'up.