; 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.

1 files changed, 39 insertions, 0 deletions

diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index 0f4a004ee90..2ea229ec907 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