# HG changeset patch
# User Stefan Monnier <monnier@iro.umontreal.ca>
# Date 1154972875 0
# Node ID e5f74bc78986cc86c412fd607a4451841362d3e5
# Parent  c49cd0ee6018381bd8785f1ca256802bac9ea9b5
(font-lock-extend-jit-lock-region-after-change): Add docstring.

diff -r c49cd0ee6018 -r e5f74bc78986 lisp/font-lock.el
--- a/lisp/font-lock.el	Mon Aug 07 17:42:36 2006 +0000
+++ b/lisp/font-lock.el	Mon Aug 07 17:47:55 2006 +0000
@@ -1173,6 +1173,13 @@
 
 (defvar jit-lock-start) (defvar jit-lock-end)
 (defun font-lock-extend-jit-lock-region-after-change (beg end old-len)
+  "Function meant for `jit-lock-after-change-extend-region-functions'.
+This function does 2 things:
+- extend the region so that it not only includes the part that was modified
+  but also the surrounding text whose highlighting may change as a consequence.
+- anticipate (part of) the region extension that will happen later in
+  `font-lock-default-fontify-region', in order to avoid the need for
+  double-redisplay in `jit-lock-fontify-now'."
   (save-excursion
     ;; First extend the region as font-lock-after-change-function would.
     (let ((region (if font-lock-extend-after-change-region-function
@@ -1198,8 +1205,11 @@
                                        'font-lock-multiline nil)
                     (point-max)))
       ;; Finally, pre-enlarge the region to a whole number of lines, to try
-      ;; and predict what font-lock-default-fontify-region will do, so as to
+      ;; and anticipate what font-lock-default-fontify-region will do, so as to
       ;; avoid double-redisplay.
+      ;; We could just run `font-lock-extend-region-functions', but since
+      ;; the only purpose is to avoid the double-redisplay, we prefer to
+      ;; do here only the part that is cheap and most likely to be useful.
       (when (memq 'font-lock-extend-region-wholelines
                   font-lock-extend-region-functions)
         (goto-char beg)