feature/tree-sitter 75b65b3f67 2/6: ; Add documentation for tree-sitter parser after-change notifiers

[Yuan Fu]

branch: feature/tree-sitter
commit 75b65b3f67eb9a4e5722780cb915b880e667d674
Author: Yuan Fu <casouri@gmail.com>
Commit: Yuan Fu <casouri@gmail.com>

    ; Add documentation for tree-sitter parser after-change notifiers
    
    * doc/lispref/parsing.texi (Using Parser): Update manual.
    * lisp/treesit.el (treesit): Add shordocs.
    * src/treesit.c: Augment docstrings.
---
 doc/lispref/parsing.texi | 39 +++++++++++++++++++++++++++++++++++++++
 lisp/treesit.el          |  5 +++++
 src/treesit.c            | 14 +++++++++++---
 3 files changed, 55 insertions(+), 3 deletions(-)

diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index 0f4a004ee9..2ea229ec90 100644
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -478,6 +478,45 @@ This function parses @var{string} using @var{language}, 
and returns
 the root node of the generated syntax tree.
 @end defun
 
+@cindex parse-tree update callback, tree-sitter
+@cindex parse-tree after-change notifer, tree-sitter
+@cindex tree-sitter parse-tree update callback
+@cindex tree-sitter parse-tree after-change notifer
+@heading Be notified by changes to the parse tree
+
+A Lisp program might want to be notified of affected text of a
+incremental parse.  For example, inserting a closing comment token
+converts text before that closing comment token into comments.  Even
+though those text are not directly edited, they are changed
+nevertheless.
+
+Emacs lets a Lisp program to register callback functions
+(@dfn{notifiers}) for this kind of changes.  A notifier function takes
+2 arguments: @var{ranges} and @var{parser}.  @var{ranges} is a list of
+cons of the form @w{@code{(@var{start} . @var{end})}}, where
+@var{start} and @var{end} marks the start and end position of a range.
+@var{parser} is the parser issuing the notification.
+
+Every time a parser reparses a buffer, it compares the old and new
+parse-tree, computes the ranges in which nodes have changed, and
+passes the ranges to notifier functions.
+
+@defun treesit-parser-add-notifier parser function
+This function adds @var{function} to @var{parser}'s after-change
+notifier functions list.  @var{function} must be a function symbol,
+rather than a lambda function.
+@end defun
+
+@defun treesit-parser-remove-notifier parser function
+This function removes @var{function} from @var{parser}'s after-change
+notifier functions list.  @var{function} must be a function symbol,
+rather than a lambda function.
+@end defun
+
+@defun treesit-parser-notifiers parser
+This function returns @var{parser}'s notifier function list.
+@end defun
+
 @node Retrieving Nodes
 @section Retrieving Nodes
 @cindex retrieve node, tree-sitter
diff --git a/lisp/treesit.el b/lisp/treesit.el
index 561d29284c..1284afe84b 100644
--- a/lisp/treesit.el
+++ b/lisp/treesit.el
@@ -2033,6 +2033,11 @@ window."
   (treesit-parser-language
    :no-eval (treesit-parser-language parser)
    :eg-result c)
+  (treesit-parser-add-notifier)
+  (treesit-parser-remove-notifier)
+  (treesit-parser-notifiers
+   :no-eval (treesit-parser-notifiers parser)
+   :eg-result (function1 function2 function3))
 
 
   "Parser ranges"
diff --git a/src/treesit.c b/src/treesit.c
index e24cabf4d0..0b9f0e98d9 100644
--- a/src/treesit.c
+++ b/src/treesit.c
@@ -1504,7 +1504,7 @@ return nil.  */)
 DEFUN ("treesit-parser-notifiers", Ftreesit_parser_notifiers,
        Streesit_parser_notifiers,
        1, 1, 0,
-       doc: /* Return the after-change functions for PARSER.  */)
+       doc: /* Return the after-change notifier functions for PARSER.  */)
   (Lisp_Object parser)
 {
   treesit_check_parser (parser);
@@ -1520,7 +1520,11 @@ DEFUN ("treesit-parser-notifiers", 
Ftreesit_parser_notifiers,
 DEFUN ("treesit-parser-add-notifier", Ftreesit_parser_add_notifier,
        Streesit_parser_add_notifier,
        2, 2, 0,
-       doc: /* Add FUNCTION to PARSER's after-change notifiers.  */)
+       doc: /* Add FUNCTION to PARSER's after-change notifiers list.
+FUNCTION must be a function symbol, rather than a lambda form.
+FUNCTION should take 2 arguments, RANGES and PARSER.  RANGES is a list
+of cons of the form (START . END), where START and END are buffer
+positions.  PARSER is the parser issuing the notification.  */)
   (Lisp_Object parser, Lisp_Object function)
 {
   treesit_check_parser (parser);
@@ -1536,7 +1540,11 @@ DEFUN ("treesit-parser-add-notifier", 
Ftreesit_parser_add_notifier,
 DEFUN ("treesit-parser-remove-notifier", Ftreesit_parser_remove_notifier,
        Streesit_parser_remove_notifier,
        2, 2, 0,
-       doc: /* Remove FUNCTION from PARSER's after-change notifiers.  */)
+       doc: /* Remove FUNCTION from PARSER's after-change notifiers
+list.  FUNCTION must be a function symbol, rather than a lambda form.
+FUNCTION should take 2 arguments, RANGES and PARSER.  RANGES is a list
+of cons of the form (START . END), where START and END are buffer
+positions.  PARSER is the parser issuing the notification.   */)
   (Lisp_Object parser, Lisp_Object function)
 {
   treesit_check_parser (parser);