master a849b56: Document 'jit-lock-bounds'

[Eli Zaretskii]

branch: master
commit a849b5641044c19ee3d8a4206c7c827e2620c325
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    Document 'jit-lock-bounds'
    
    * doc/lispref/modes.texi (Other Font Lock Variables):
    * lisp/jit-lock.el (jit-lock-functions, jit-lock-register):
    Document the return value of the fontification functions.
---
 doc/lispref/modes.texi |  5 +++++
 lisp/jit-lock.el       | 10 ++++++++--
 2 files changed, 13 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 951f30f..ee55f98 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -3315,6 +3315,11 @@ This function tells Font Lock mode to run the Lisp 
function
 current buffer.  It calls @var{function} before calling the default
 fontification functions, and gives it two arguments, @var{start} and
 @var{end}, which specify the region to be fontified or refontified.
+If @var{function} performs fontifications, it can return a list of the
+form @w{@code{(jit-lock-bounds @var{beg} . @var{end})}}, to indicate
+the bounds of the region it actually fontified; JIT font-lock will use
+this information to optimize subsequent redisplay cycles and regions
+of buffer text it will pass to future calls to @var{function}.
 
 The optional argument @var{contextual}, if non-@code{nil}, forces Font
 Lock mode to always refontify a syntactically relevant part of the
diff --git a/lisp/jit-lock.el b/lisp/jit-lock.el
index a128792..a905936 100644
--- a/lisp/jit-lock.el
+++ b/lisp/jit-lock.el
@@ -150,7 +150,10 @@ If 0, then fontification is only deferred while there is 
input pending."
 (defvar jit-lock-functions nil
   "Special hook run to do the actual fontification.
 The functions are called with two arguments:
-the START and END of the region to fontify.")
+the START and END of the region to fontify.
+Each function can return a list of the form (jit-lock-bounds BEG . END),
+to indicate the bounds of the region it actually fontified;
+JIT font-lock will use this information to optimize redisplay cycles.")
 
 (defvar-local jit-lock-context-unfontify-pos nil
   "Consider text after this position as contextually unfontified.
@@ -332,7 +335,10 @@ like `debug-on-error' and Edebug can be used."
   "Register FUN as a fontification function to be called in this buffer.
 FUN will be called with two arguments START and END indicating the region
 that needs to be (re)fontified.
-If non-nil, CONTEXTUAL means that a contextual fontification would be useful."
+If non-nil, CONTEXTUAL means that a contextual fontification would be useful.
+FUN can return a list of the form (jit-lock-bounds BEG . END),
+to indicate the bounds of the region it actually fontified; JIT
+font-lock will use this information to optimize redisplay cycles."
   (add-hook 'jit-lock-functions fun nil t)
   (when (and contextual jit-lock-contextually)
     (setq-local jit-lock-contextually t))