Add handling of contextual entities in tree-sitter font-lock

* lisp/progmodes/python.el: Remove function.
(python--treesit-settings): Capture contextual node.
* lisp/treesit.el (treesit--set-nonsticky):
(treesit-font-lock-contextual-post-process): New functions.
(treesit-font-lock-fontify-region): Change local variable START and
END to NODE-START and NODE-END, handle special capture name
"contextual".
* doc/lispref/modes.texi (Parser-based Font Lock): Update manual.

1 files changed, 20 insertions, 0 deletions

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 3c91893bbfd..c6f848ffb23 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -3992,6 +3992,26 @@ priority.  If a capture name is neither a face nor a function, it is
 ignored.
 @end defun
 
+Contextual entities, like multi-line strings, or @code{/* */} style
+comments, need special care, because change in these entities might
+cause change in a large portion of the buffer.  For example, inserting
+the closing comment delimiter @code{*/} will change all the text
+between it and the opening delimiter to comment face.  Such entities
+should be captured in a special name @code{contextual}, so Emacs can
+correctly update their fontification.  Here is an example for
+comments:
+
+@example
+@group
+(treesit-font-lock-rules
+ :language 'javascript
+ :feature 'comment
+ :override t
+ '((comment) @@font-lock-comment-face)
+   (comment) @@contextual))
+@end group
+@end example
+
 @defvar treesit-font-lock-feature-list
 This is a list of lists of feature symbols.  Each element of the list
 is a list that represents a decoration level.