2 files changed, 22 insertions, 20 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
diff --git a/lisp/treesit.el b/lisp/treesit.el
index dd7895683ff..0de0e283c3b 100644
--- a/lisp/treesit.el
+++ b/lisp/treesit.el
@@ -1561,11 +1561,11 @@ Normally Emacs stops at the first defun it encounters.  If this
 variable's value is t, Emacs tries to find the top-level defun,
 and ignores nested ones.
 
-This variable can also be a list of cons cells of the form (FROM
-. TO), where FROM and TO are tree-sitter node type regexps.  When
-Emacs finds a defun node whose type matches any of the FROM
-regexp in the list, Emacs then tries to find the top-level node
-matching the corresponding TO regexp.")
+This variable can also be a list of cons cells of the
+form (FROM . TO), where FROM and TO are tree-sitter node type
+regexps.  When Emacs finds a defun node whose type matches any of
+the FROM regexps in the list, it then tries to find a
+higher-level node matching the corresponding TO regexp.")
 
 (defun treesit--defun-maybe-top-level (node)
   "Maybe return the top-level equivalent of NODE.