; Fix recently added treesit documentation

* lisp/treesit.el (treesit-defun-prefer-top-level):
* doc/lispref/positions.texi (List Motion): Fix wording.

1 files changed, 17 insertions, 15 deletions

diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
index c065cc11e25..7acf2d052a8 100644
--- a/doc/lispref/positions.texi
+++ b/doc/lispref/positions.texi
@@ -836,35 +836,37 @@ of using its normal method.
 
 @findex treesit-beginning-of-defun
 @findex treesit-end-of-defun
-If Emacs is compiled with tree-sitter, it can use the tree-sitter parser
-information to move across syntax constructs.  A major mode can set
-@code{treesit-defun-type-regexp} and get navigation functionality for
-free, by using @code{treesit-beginning-of-defun} and
-@code{treesit-end-of-defun}.
+If Emacs is compiled with tree-sitter, it can use the tree-sitter
+parser information to move across syntax constructs.  Since what
+exactly is considered a defun varies between languages, a major mode
+should set @code{treesit-defun-type-regexp} to determine that.  Then
+the mode can get navigation-by-defun functionality for free, by using
+@code{treesit-beginning-of-defun} and @code{treesit-end-of-defun}.
 
 @defvar treesit-defun-type-regexp
 The value of this variable is a regexp matching the node type of defun
-nodes.  (For ``node'', ``node type'', @pxref{Parsing Program Source}.)
+nodes.  (For ``node'' and ``node type'', @pxref{Parsing Program Source}.)
 
 For example, @code{python-mode} sets this variable to a regexp that
 matches either @code{function_definition} or @code{class_definition}.
 @end defvar
 
 @defvar treesit-defun-prefer-top-level
-If this variable is non-@code{nil}, Emacs skips nested defun and
-prefers the top-level defun.
+If this variable is non-@code{nil}, Emacs skips nested defuns, when it
+looks for beginning and end of a defun, and prefers to go to the
+top-level defun instead.
 
-In some languages, a defun could be nested in another one.  Normally
-Emacs stops at the first defun it encounters.  If this variable's
+In some languages, a defun could be nested in another one.  By default,
+Emacs stops at the first defun it encounters.  But if this variable's
 value is @code{t}, whenever Emacs finds a defun node, it tries to go
-up the parse tree and find the top-level defun.
+up the parse tree until it finds the top-level defun.
 
 This variable can also be a list of cons cells of the form
 @w{@code{(@var{from} . @var{to}))}}, where @var{from} and @var{to} are
-regexp matching tree-sitter node types.  When Emacs finds a defun node
-whose type matches any of the @var{from} regexp in the list, Emacs
-then tries to go up the parse tree to find the top-level node matching
-the corresponding @var{to} regexp.
+regexps matching tree-sitter node types.  When Emacs finds a defun
+node whose type matches any of the @var{from} regexps in the list, it
+then tries to go up the parse tree until it finds a higher-level node
+matching the corresponding @var{to} regexp.
 @end defvar
 
 @node Skipping Characters