feature/tree-sitter 31ad906bd0 2/3: Add manual entry for tree-sitter search functions

[Yuan Fu]

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

    Add manual entry for tree-sitter search functions
    
    * doc/lispref/parsing.texi (Retrieving Node): New subsection
    "Searching for node".
    * doc/lispref/positions.texi (List Motion): Add entries for
    treesit-defun-query, treesit-beginning-of-defun, treesit-end-of-defun.
    * lisp/treesit.el (treesit-search-forward, treesit-search-beginning)
    (treesit-search-end): Minor docstring fix-up.
---
 doc/lispref/parsing.texi   | 32 ++++++++++++++++++++++++++++++++
 doc/lispref/positions.texi | 26 ++++++++++++++++++++++++++
 lisp/treesit.el            | 11 ++++-------
 3 files changed, 62 insertions(+), 7 deletions(-)

diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index 917779f78a..6d5c7b8dc2 100644
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -591,6 +591,38 @@ that spans the range from @var{beg} to @var{end}.  It is 
similar to
 for named child (@pxref{tree-sitter named node, named node}).
 @end defun
 
+@heading Searching for node
+
+@defun treesit-search-beginning query arg &optional lang up-only
+This function searches for the next node that @var{query} captures,
+starting at point.  Use the parser in current buffer that has
+@var{lang} as its language, if @var{lang} is nil, use the first parser
+in current buffer’s buffer list.
+
+This function stops at the @var{arg}'th match.  If @var{arg} is
+negative, search backward.  If the search succeeds, stop at the
+beginning of the matched node and return the node.  Return nil if
+search failed.
+
+By default, this function searches by traversing the parse tree depth
+first, starting from the node at point.  If @var{up-only} is non-nil,
+this function only go to siblings and parents, but never go down into
+children nodes.
+@end defun
+
+@defun treesit-search-end query arg &optional lang up-only
+This function is like @code{treesit-search-beginning}, but stops at
+the end of the matched node.
+@end defun
+
+@defun treesit-search-forward pos-fn arg query &optional lang up-only
+This function is like @code{treesit-search-beginning} and
+@code{treesit-search-end}, but instead of stopping at the beginning or
+end of the matched node, it determines where to stop by @var{pos-fn},
+where @var{pos-fn} is a function that takes a node and returns a
+position
+@end defun
+
 @heading More convenient functions
 
 @defun treesit-filter-child node pred &optional named
diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
index 7945232bf8..809ac207d2 100644
--- a/doc/lispref/positions.texi
+++ b/doc/lispref/positions.texi
@@ -834,6 +834,32 @@ a defun.  The function @code{end-of-defun} calls this 
function instead
 of using its normal method.
 @end defvar
 
+When tree-sitter support is available (@pxref{Parsing Program
+Source}), Emacs can find the beginning and end of a function according
+to the syntax tree.
+
+@defvar treesit-defun-query
+Set this variable to a tree-sitter query that matches defun
+definitions, then @code{treesit-beginning-of-defun} and
+@code{treesit-end-of-defun} can find the beginning and end of a defun.
+
+Make sure to use a compiled query for this variable, otherwise
+@code{treesit-beginning-of-defun} and @code{treesit-end-of-defun} will
+be very slow.
+@end defvar
+
+@defun treesit-beginning-of-defun &optional arg
+This function finds the beginning of a defun according to
+@var{treesit-defun-query}.  This function is suitable for the value of
+@var{beginning-of-defun-function}.
+@end defun
+
+@defun treesit-end-of-defun &optional arg
+This function finds the end of a defun according to
+@var{treesit-defun-query}.  This function is suitable for the value of
+@var{end-of-defun-function}.
+@end defun
+
 @node Skipping Characters
 @subsection Skipping Characters
 @cindex skipping characters
diff --git a/lisp/treesit.el b/lisp/treesit.el
index b969f18514..9c66f32ec2 100644
--- a/lisp/treesit.el
+++ b/lisp/treesit.el
@@ -862,9 +862,6 @@ indentation (target) is in green, current indentation is in 
red."
 (defun treesit-search-forward (pos-fn arg query &optional lang up-only)
   "Search forward for nodes that matches QUERY from current point.
 
-This is a more primitive function, you might want to use
-`treesit-search-beginning' or `treesit-search-end' instead.
-
 QUERY has to capture the node to match.  LANG specifies the
 language in which we search for nodes.  If LANG is nil, use the
 first parser in (`treesit-parser-list').
@@ -875,7 +872,7 @@ negative ARG means go backward.
 POS-FN can be either `treesit-node-start' or `treesit-node-end',
 or any function that takes a node and returns a position.
 
-If search succeeds, stop at the position returned by POS-FN and
+If the search succeeds, stop at the position returned by POS-FN and
 return the matched node.  Return nil if search failed.
 
 We search by traversing the parse tree, visiting every node
@@ -925,12 +922,12 @@ Stops at the beginning of matched node.
 
 QUERY has to capture the node to match.  LANG specifies the
 language in which we search for nodes.  If LANG is nil, use the
-first parser in (`treesit-parser-list').
+first parser in current buffer's parser list.
 
 Move forward/backward ARG times, positive ARG means go forward,
 negative ARG means go backward.
 
-If search succeeds, return the matched node.  Return nil if
+If the search succeeds, return the matched node.  Return nil if
 search failed.
 
 We search by traversing the parse tree, visiting every node
@@ -953,7 +950,7 @@ first parser in (`treesit-parser-list').
 Move forward/backward ARG times, positive ARG means go forward,
 negative ARG means go backward.
 
-If search succeeds, return the matched node.  Return nil if
+If the search succeeds, return the matched node.  Return nil if
 search failed.
 
 We search by traversing the parse tree, visiting every node