diff options
| -rw-r--r-- | doc/lispref/positions.texi | 32 | ||||
| -rw-r--r-- | lisp/treesit.el | 10 |
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. |