From: Eli Zaretskii Date: Sun, 25 Dec 2022 07:29:47 +0000 (+0200) Subject: ; Fix recent changes in treesit documentation X-Git-Tag: emacs-29.0.90~1006 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=ecee3bd4209811118bb3d8ad90e6d1a5acfccc85;p=emacs.git ; Fix recent changes in treesit documentation * lisp/treesit.el (treesit-defun-name-function, treesit-node-at) (treesit-node-on): Doc fixes. * doc/lispref/parsing.texi (Tree-sitter major modes): Fix wording, punctuation, and indexing. (Retrieving Nodes): Fix wording and add cross-references. --- diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi index 918e197676e..6f207123598 100644 --- a/doc/lispref/parsing.texi +++ b/doc/lispref/parsing.texi @@ -580,8 +580,8 @@ If @var{parser-or-lang} is a parser object, this function uses that parser; if @var{parser-or-lang} is a language, this function uses the first parser for that language in the current buffer, or creates one if none exists; if @var{parser-or-lang} is @code{nil}, this function -tries to guess the language at @var{pos} by -@code{treesit-language-at}. +tries to guess the language at @var{pos} by calling +@code{treesit-language-at} (@pxref{Multiple Languages}). If this function cannot find a suitable node to return, it returns @code{nil}. @@ -616,7 +616,7 @@ If @var{parser-or-lang} is a parser object, this function uses that parser; if @var{parser-or-lang} is a language, this function uses the first parser for that language in the current buffer, or creates one if none exists; if @var{parser-or-lang} is @code{nil}, this function -tries to guess the language at @var{beg} by +tries to guess the language at @var{beg} by calling @code{treesit-language-at}. If @var{named} is non-@code{nil}, this function looks for a named node @@ -1717,16 +1717,22 @@ This function activates some tree-sitter features for a major mode. Currently, it sets up the following features: @itemize +@cindex treesit-font-lock-settings @item If @code{treesit-font-lock-settings} is non-@code{nil}, it sets up fontification. + +@cindex treesit-simple-indent-rules @item If @code{treesit-simple-indent-rules} is non-@code{nil}, it sets up indentation. + +@cindex treesit-defun-type-regexp @item If @code{treesit-defun-type-regexp} is non-@code{nil}, it sets up navigation functions for @code{beginning-of-defun} and @code{end-of-defun}. + @item If @code{treesit-defun-name-function} is non-@code{nil}, it sets up add-log functions used by @code{add-log-current-defun}. @@ -1747,9 +1753,9 @@ provides some additional functions for working with defuns: @defun treesit-defun-at-point This function returns the defun node at point, or @code{nil} if none -is found. It respects @code{treesit-defun-tactic}: it returns the -top-level defun if the value is @code{top-level}, and returns the -immediate enclosing defun if the value is @code{nested}. +is found. It respects @code{treesit-defun-tactic}: if its value is +@code{top-level}, this function returns the top-level defun, and if +its value is @code{nested}, it returns the immediate enclosing defun. This function requires @code{treesit-defun-type-regexp} to work. If it is @code{nil}, this function simply returns @code{nil}. @@ -1760,19 +1766,20 @@ This function returns the defun name of @var{node}. It returns @code{nil} if there is no defun name for @var{node}, or if @var{node} is not a defun node, or if @var{node} is @code{nil}. -The defun name is names like function name, class name, struct name, -etc. +Depending on the language and major mode, the defun names are names +like function name, class name, struct name, etc. If @code{treesit-defun-name-function} is @code{nil}, this function always returns @code{nil}. @end defun @defvar treesit-defun-name-function -If non-@code{nil}, this variable should store a function that is -called with a node and returns the defun name of it. The function -should have the same semantic as @code{treesit-defun-name}: if the -node is not a defun node, or the node is a defun node but doesn't have -a name, or the node is @code{nil}, return @code{nil}. +If non-@code{nil}, this variable's value should be a function that is +called with a node as its argument, and returns the defun name of the +node. The function should have the same semantic as +@code{treesit-defun-name}: if the node is not a defun node, or the +node is a defun node but doesn't have a name, or the node is +@code{nil}, it should return @code{nil}. @end defvar @node Tree-sitter C API diff --git a/lisp/treesit.el b/lisp/treesit.el index 0eacd4075f8..5ec6f90afa3 100644 --- a/lisp/treesit.el +++ b/lisp/treesit.el @@ -174,8 +174,7 @@ only look for named nodes. If PARSER-OR-LANG is a parser, use that parser; if PARSER-OR-LANG is a language, find the first parser for that language in the current buffer, or create one if none exists; If PARSER-OR-LANG -is nil, try to guess the language at POS by -`treesit-language-at'." +is nil, try to guess the language at POS using `treesit-language-at'." (let* ((root (if (treesit-parser-p parser-or-lang) (treesit-parser-root-node parser-or-lang) (treesit-buffer-root-node @@ -224,8 +223,7 @@ named node. If PARSER-OR-LANG is a parser, use that parser; if PARSER-OR-LANG is a language, find the first parser for that language in the current buffer, or create one if none exists; If PARSER-OR-LANG -is nil, try to guess the language at BEG by -`treesit-language-at'." +is nil, try to guess the language at BEG using `treesit-language-at'." (let ((root (if (treesit-parser-p parser-or-lang) (treesit-parser-root-node parser-or-lang) (treesit-buffer-root-node @@ -1613,8 +1611,8 @@ newline after a defun, or the beginning of a defun. If the value is nil, no skipping is performed.") (defvar-local treesit-defun-name-function nil - "A function called with a node and returns the name of it. -If the node is a defun node, return the defun name. E.g., the + "A function that is called with a node and returns its defun name or nil. +If the node is a defun node, return the defun name, e.g., the function name of a function. If the node is not a defun node, or the defun node doesn't have a name, or the node is nil, return nil.")