Improve documentation of 'jit-lock-contextually'

* lisp/jit-lock.el (jit-lock-contextually): Clarify the jit-lock
operation when 'jit-lock-contextually' is non-nil and non-t.

* doc/lispref/modes.texi (Syntactic Font Lock)
(Other Font Lock Variables): Document the relation between
'jit-lock-register', 'font-lock-keywords-only', and syntactic
refontification.

2 files changed, 24 insertions, 9 deletions

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index a8ddd45f891..e685391c955 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -3214,6 +3214,11 @@ The optional argument @var{contextual}, if non-@code{nil}, forces Font
 Lock mode to always refontify a syntactically relevant part of the
 buffer, and not just the modified lines.  This argument can usually be
 omitted.
+
+When Font Lock is activated in a buffer, it calls this function with a
+non-@code{nil} value of @var{contextual} if the value of
+@code{font-lock-keywords-only} (@pxref{Syntactic Font Lock}) is
+@code{nil}.
 @end defun
 
 @defun jit-lock-unregister function
@@ -3380,7 +3385,11 @@ table in special cases.  @xref{Syntax Properties}.
 If the value of this variable is non-@code{nil}, Font Lock does not do
 syntactic fontification, only search-based fontification based on
 @code{font-lock-keywords}.  It is normally set by Font Lock mode based
-on the @var{keywords-only} element in @code{font-lock-defaults}.
+on the @var{keywords-only} element in @code{font-lock-defaults}.  If
+the value is @code{nil}, Font Lock will call @code{jit-lock-register}
+(@pxref{Other Font Lock Variables}) to set up for automatic
+refontification of buffer text following a modified line to reflect
+the new syntactic context due to the change.
 @end defvar
 
 @defvar font-lock-syntax-table
diff --git a/lisp/jit-lock.el b/lisp/jit-lock.el
index d73cd74da0b..95cc02197c1 100644
--- a/lisp/jit-lock.el
+++ b/lisp/jit-lock.el
@@ -101,16 +101,22 @@ See also `jit-lock-stealth-nice'."
 
 (defvaralias 'jit-lock-defer-contextually 'jit-lock-contextually)
 (defcustom jit-lock-contextually 'syntax-driven
-  "If non-nil, means fontification should be syntactically true.
-If nil, means fontification occurs only on those lines modified.  This
+  "If non-nil, fontification should be syntactically true.
+If nil, refontification occurs only on lines that were modified.  This
 means where modification on a line causes syntactic change on subsequent lines,
 those subsequent lines are not refontified to reflect their new context.
-If t, means fontification occurs on those lines modified and all
-subsequent lines.  This means those subsequent lines are refontified to reflect
-their new syntactic context, after `jit-lock-context-time' seconds.
-If any other value, e.g., `syntax-driven', means syntactically true
-fontification occurs only if syntactic fontification is performed using the
-buffer mode's syntax table, i.e., only if `font-lock-keywords-only' is nil.
+If t, fontification occurs on those lines modified and all subsequent lines.
+This means those subsequent lines are refontified to reflect their new
+syntactic context, after `jit-lock-context-time' seconds.
+If any other value, e.g., `syntax-driven', it means refontification of
+subsequent lines to reflect their new syntactic context may or may not
+occur after `jit-lock-context-time', depending on the the font-lock
+definitions of the buffer.  Specifically, if `font-lock-keywords-only'
+is nil in a buffer, which generally means the syntactic fontification
+is done using the buffer mode's syntax table, the syntactic
+refontification will be triggered (because in that case font-lock
+calls `jit-lock-register' to set up for syntactic refontification,
+and sets the buffer-local value of `jit-lock-contextually' to t).
 
 The value of this variable is used when JIT Lock mode is turned on."
   :type '(choice (const :tag "never" nil)