Fix recent changes in documentation

* lisp/treesit.el (treesit-node-at): Doc fix.

* doc/lispref/parsing.texi (Language Definitions): Add
cross-reference.
(Retrieving Nodes): Renamed from "Retrieving Node"; all references
changed.
(Retrieving Nodes): Fix wording and markup.

diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi
index e79c8cef180cc9bb820c2b922cf6e503286c417e..b1bbe5e0a96a64c68786057cdda5426d3b968de8 100644 (file)
--- a/doc/lispref/elisp.texi
+++ b/doc/lispref/elisp.texi
@@ -1366,7 +1366,7 @@ Parsing Program Source
 
 * Language Definitions::     Loading tree-sitter language definitions.
 * Using Parser::             Introduction to parsers.
-* Retrieving Node::          Retrieving node from syntax tree.
+* Retrieving Nodes::         Retrieving nodes from a syntax tree.
 * Accessing Node Information:: Accessing node information.
 * Pattern Matching::         Pattern matching with query patterns.
 * Multiple Languages::       Parse text written in multiple languages.

diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index f690e6a60470362dbb568d5e2f78ea921936200b..2c838e317e5643b72f22d5041a3c152dbed3562f 100644 (file)
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -41,7 +41,7 @@ source files that mix multiple programming languages.
 @menu
 * Language Definitions::     Loading tree-sitter language definitions.
 * Using Parser::             Introduction to parsers.
-* Retrieving Node::          Retrieving node from syntax tree.
+* Retrieving Nodes::         Retrieving nodes from a syntax tree.
 * Accessing Node Information:: Accessing node information.
 * Pattern Matching::         Pattern matching with query patterns.
 * Multiple Languages::       Parse text written in multiple languages.
@@ -337,7 +337,8 @@ language definition.
 @item token(@var{rule})
 marks @var{rule} to produce a single leaf node.  That is, instead of
 generating a parent node with individual child nodes under it,
-everything is combined into a single leaf node.
+everything is combined into a single leaf node.  @xref{Retrieving
+Nodes}.
 @item token.immediate(@var{rule})
 Normally, grammar rules ignore preceding whitespace; this
 changes @var{rule} to match only when there is no preceding
@@ -461,8 +462,8 @@ This function parses @var{string} using @var{language}, and returns
 the root node of the generated syntax tree.
 @end defun
 
-@node Retrieving Node
-@section Retrieving Node
+@node Retrieving Nodes
+@section Retrieving Nodes
 @cindex retrieve node, tree-sitter
 @cindex tree-sitter, find node
 @cindex get node, tree-sitter
@@ -487,28 +488,27 @@ Nodes are not automatically updated when the associated buffer is
 modified, and there is no way to update a node once it is retrieved.
 Using an outdated node signals the @code{treesit-node-outdated} error.
 
-@heading Retrieving node from syntax tree
+@heading Retrieving nodes from syntax tree
 @cindex retrieving tree-sitter nodes
 @cindex syntax tree, retrieving nodes
 
+@cindex leaf node, of tree-sitter parse tree
+@cindex tree-sitter parse tree, leaf node
 @defun treesit-node-at pos &optional parser-or-lang named
-This function returns a @emph{leaf} node at buffer position @var{pos}.
+This function returns a @dfn{leaf} node at buffer position @var{pos}.
 A leaf node is a node that doesn't have any child nodes.
 
 This function tries to return a node whose span covers @var{pos}: the
-node's beginning is less or equal to @var{pos}, and the node's end is
-greater or equal to @var{pos}.
+node's beginning position is less or equal to @var{pos}, and the
+node's end position is greater or equal to @var{pos}.
 
-But if no leaf node's span covers @var{pos} (e.g., @var{pos} is on the
+If no leaf node's span covers @var{pos} (e.g., @var{pos} is in the
 whitespace between two leaf nodes), this function returns the first
 leaf node after @var{pos}.
 
 Finally, if there is no leaf node after @var{pos}, return the first
 leaf node before @var{pos}.
 
-If @var{pos} is in between two adjacent nodes, this function returns
-the one after @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
@@ -517,10 +517,10 @@ parser using that language in @code{(treesit-parser-list)}, and uses
 that.
 
 If this function cannot find a suitable node to return, it returns
-nil.
+@code{nil}.
 
-If @var{named} is non-@code{nil}, this function looks for a named node
-only (@pxref{tree-sitter named node, named node}).
+If @var{named} is non-@code{nil}, this function looks only for named
+nodes (@pxref{tree-sitter named node, named node}).
 
 Example:
 
@@ -570,7 +570,7 @@ parser, it returns @code{nil}.
 Given a node, a Lisp program can retrieve other nodes starting from
 it, or query for information about this node.
 
-@heading Retrieving node from other nodes
+@heading Retrieving nodes from other nodes
 @cindex syntax tree nodes, retrieving from other nodes
 
 @subheading By kinship

diff --git a/lisp/treesit.el b/lisp/treesit.el
index 4d1a6bdf827a59df1cfea5af9c632e7991fd02d5..1070b66f704940ab0ccd811948afa5a997e36685 100644 (file)
--- a/lisp/treesit.el
+++ b/lisp/treesit.el
@@ -173,8 +173,8 @@ parser in `treesit-parser-list', or nil if there is no parser."
 
 A leaf node is a node that doesn't have any child nodes.
 
-The returned node's span covers POS: the node's beginning is less
-or equal to POS, and the node's end is greater or equal to POS.
+The returned node's span covers POS: the node's beginning is before
+or at POS, and the node's end is at or after POS.
 
 If no leaf node's span covers POS (e.g., POS is on whitespace
 between two leaf nodes), return the first leaf node after POS.
@@ -182,9 +182,6 @@ between two leaf nodes), return the first leaf node after POS.
 If there is no leaf node after POS, return the first leaf node
 before POS.
 
-If POS is in between two adjacent nodes, return the one after
-POS.
-
 Return nil if no leaf node can be returned.  If NAMED is non-nil,
 only look for named nodes.