From: Yuan Fu <casouri@gmail.com>
Date: Sun, 23 Oct 2022 21:23:59 +0000 (-0700)
Subject: ; Resolve FIXME's in tree-sitter manual sections
X-Git-Tag: emacs-29.0.90~1801
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=6a2399c55e9505be06cb98ffbe1a3878f9e96fb2;p=emacs.git

; Resolve FIXME's in tree-sitter manual sections

* doc/lispref/modes.texi (Parser-based Indentation):
* doc/lispref/parsing.texi (Retrieving Node): Resolve FIXME's.
* src/treesit.c: Update tree graph in docstring.
---

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index c6269b46ba0..d73c443b4c2 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -4820,12 +4820,11 @@ available default functions are:
 
 @ftable @code
 @item no-node
-@c FIXME: How many arguments does no-node accept, and what are thos
-@c arguments?
-This matcher is a function that matches the case where @var{node} is
-@code{nil}, i.e., there is no node that starts at @var{bol}.  This is
-the case when @var{bol} is on an empty line or inside a multi-line
-string, etc.
+This matcher is a function that is called with 3 arguments:
+@var{node}, @var{parent}, and @var{bol}, and returns non-@code{nil},
+indicating a match, if @var{node} is @code{nil}, i.e., there is no
+node that starts at @var{bol}.  This is the case when @var{bol} is on
+an empty line or inside a multi-line string, etc.
 
 @item parent-is
 This matcher is a function of one argument, @var{type}; it returns a
diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index aaa8f0f64dd..ec6cd2757d8 100644
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -655,19 +655,19 @@ Like @code{treesit-search-subtree}, this function also traverses the
 parse tree and matches each node with @var{predicate} (except for
 @var{start}), where @var{predicate} can be a (case-insensitive) regexp
 or a function.  For a tree like the below where @var{start} is marked
-1, this function traverses as numbered:
+S, this function traverses as numbered from 1 to 12:
 
 @example
 @group
-              16
+              12
               |
-     3--------7-----------15
-     |        |           |
-o--1-+--2  4--+--6    10--+-----14
-|  |             |    |         |
-o  o             5  +-+-+    +--+--+
-                    |   |    |  |  |
-                    8   9    11 12 13
+     S--------3----------11
+     |        |          |
+o--o-+--o  1--+--2    6--+-----10
+|  |                  |        |
+o  o                +-+-+   +--+--+
+                    |   |   |  |  |
+                    4   5   7  8  9
 @end group
 @end example
 
@@ -679,12 +679,14 @@ named nodes by default, but if @var{all} is non-@code{nil}, it
 searches for all nodes.  If @var{backward} is non-@code{nil}, it
 searches backwards.
 
-@c FIXME: Still not very clear: the difference between ``traverse
-@c a subtree of a node'' and ``traverse every node that comes after
-@c it''.
 While @code{treesit-search-subtree} traverses the subtree of a node,
-this function usually starts with a leaf node and traverses every node
-that comes after it in the buffer position order.  It is useful for
+this function starts with node @var{start} and traverses every node
+that comes after it in the buffer position order, i.e., nodes with
+start positions greater than the end position of @var{start}.
+
+In the tree shown above, @code{treesit-search-subtree} traverses node
+S (@var{start}) and nodes marked with @code{o}, where this function
+traverses the nodes marked with numbers.  This function is useful for
 answering questions like ``what is the first node after @var{start} in
 the buffer that satisfies some condition?''
 @end defun
diff --git a/src/treesit.c b/src/treesit.c
index b4dac587b1a..a23ac7510da 100644
--- a/src/treesit.c
+++ b/src/treesit.c
@@ -2548,17 +2548,18 @@ for all nodes.  If BACKWARD is non-nil, search backwards.
 
 Return the first matched node, or nil if none matches.
 
-For a tree like below, where START is marked by 1, traverse as
-numbered:
-                16
-                |
-       3--------7-----------15
-       |        |           |
-  o--1-+--2  4--+--6    10--+-----14
-  |  |             |    |         |
-  o  o             5  +-+-+    +--+--+
-                      |   |    |  |  |
-                      8   9    11 12 13
+For a tree like below, where START is marked by S, traverse as
+numbered from 1 to 12:
+
+		12
+		|
+       S--------3----------11
+       |        |          |
+  o--o-+--o  1--+--2    6--+-----10
+  |  |                  |        |
+  o  o                +-+-+   +--+--+
+		      |   |   |  |  |
+		      4   5   7  8  9
 
 Note that this function doesn't traverse the subtree of START, and it
 always traverse leaf nodes first, then upwards.  */)