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

@@ -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

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

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