Make treesit-node-at/on guess language at point

If PARSER-OR-LANG is nil, it makes more sense to guess the language at
point by treesit-language-at than to simply use the first parser in
the parser list.

* doc/lispref/parsing.texi (Retrieving Nodes): Update manual.
* lisp/treesit.el (treesit-node-at)
(treesit-node-on): Guess language at point.  Update docstring.
(treesit-buffer-root-node): Update docstring.

1 files changed, 17 insertions, 15 deletions

diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index adb4c5e6e0c..e213363298d 100644
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -576,12 +576,12 @@ leaf node after @var{pos}.
 Finally, if there is no leaf node after @var{pos}, return the first
 leaf node before @var{pos}.
 
-When @var{parser-or-lang} is @code{nil} or omitted, this function uses
-the first parser in @code{(treesit-parser-list)} of the current
-buffer.  If @var{parser-or-lang} is a parser object, it uses that
-parser; if @var{parser-or-lang} is a language, it finds the first
-parser using that language in @code{(treesit-parser-list)}, and uses
-that.
+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}.
 
 If this function cannot find a suitable node to return, it returns
 @code{nil}.
@@ -610,13 +610,14 @@ is at or after @var{end}.
 inside any top-level construct (function definition, etc.) most
 probably will give you the root node, because the root node is the
 smallest node that covers that empty line.  Most of the time, you want
-to use @code{treesit-node-at}, described above, instead.
+to use @code{treesit-node-at} instead.
 
-When @var{parser-or-lang} is @code{nil}, this function uses the first
-parser in @code{(treesit-parser-list)} of the current buffer.  If
-@var{parser-or-lang} is a parser object, it uses that parser; if
-@var{parser-or-lang} is a language, it finds the first parser using
-that language in @code{(treesit-parser-list)}, and uses that.
+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
+@code{treesit-language-at}.
 
 If @var{named} is non-@code{nil}, this function looks for a named node
 only (@pxref{tree-sitter named node, named node}).
@@ -628,9 +629,10 @@ This function returns the root node of the syntax tree generated by
 @end defun
 
 @defun treesit-buffer-root-node &optional language
-This function finds the first parser that uses @var{language} in
-@code{(treesit-parser-list)} of the current buffer, and returns the
-root node generated by that parser.  If it cannot find an appropriate
+This function finds the first parser for @var{language} in the current
+buffer, or creates one if none exists, and returns the root node
+generated by that parser.  If @var{language} is omitted, it uses the
+first parser in the parser list.  If it cannot find an appropriate
 parser, it returns @code{nil}.
 @end defun