Minor copyedits of 'jit-lock-antiblink-grace's docs

* lisp/jit-lock.el (jit-lock-antiblink-grace):
* etc/NEWS (value): Reword the NEWS entry and the doc string.

2 files changed, 23 insertions, 19 deletions

diff --git a/etc/NEWS b/etc/NEWS
index d4f31aeb85d..28bcb720cde 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -632,13 +632,6 @@ If the region is active, the command joins all the lines in the
 region.  When there's no active region, the command works on the
 current and the previous or the next line, as before.
 
----
-** New customizable variable 'jit-lock-antiblink-grace'.
-When typing strings, this helps avoid "blinking", an oscillation
-between string and non-string fontification.  The variable holds a
-number of seconds (default is 2) before a potentially unwanted
-fontification starts.  Set to nil to get back the old behavior.
-
 
 * Changes in Specialized Modes and Packages in Emacs 27.1
 
@@ -654,6 +647,17 @@ font locking for a mode.  It recomputes the font locking data and then
 re-fontifies the buffer.
 
 ---
+** Font Lock is smarter about fontifying unterminated strings and comments.
+When you type a quote that starts a string, or a comment delimiter
+that starts a comment, font-lock will not immediately refontify the
+following characters in font-lock-string-face or
+font-lock-comment-face.  Instead, it will delay the fontification
+beyond the current line to give you a chance to close the string or
+comment.  This is controlled by the new customizable variable
+'jit-lock-antiblink-grace', which specifies the delay in seconds.  The
+default is 2 seconds; set to nil to get back the old behavior.
+
+---
 ** The 'C' command in 'tar-mode' will now preserve the timestamp of
 the extracted file if the new user option 'tar-copy-preserve-time' is
 non-nil.
diff --git a/lisp/jit-lock.el b/lisp/jit-lock.el
index a17224e4bd0..0586eb7bf08 100644
--- a/lisp/jit-lock.el
+++ b/lisp/jit-lock.el
@@ -124,14 +124,14 @@ The value of this variable is used when JIT Lock mode is turned on."
   :group 'jit-lock)
 
 (defcustom jit-lock-antiblink-grace 2
-  "Grace period after which to refontify due to unterminated strings.
-If nil, no grace period is given.  Otherwise, a newly created
-unterminated string is fontified only to the end of the current
-line, after which the system waits this many seconds of idle time
-before deciding the string is multi-line and fontifying the
-remaining lines.  When typing strings, this helps avoid
-\"blinking\", an unwanted oscillation between string and
-non-string fontification."
+  "Delay after which to refontify unterminated strings and comments.
+If nil, no grace period is given; unterminated strings and comments
+are refontified immediately.  If a number, a newly created
+unterminated string or comment is fontified only to the end of the
+current line, after which fontification waits that many seconds of idle
+time before refontifying the remaining lines.  When typing strings
+and comments, the delay helps avoid unpleasant \"blinking\", between
+string/comment and non-string/non-comment fontification."
   :type '(choice (const :tag "never" nil)
                  (number :tag "seconds"))
   :group 'jit-lock
@@ -725,19 +725,19 @@ will take place when text is fontified stealthily."
              (cancel-timer jit-lock--antiblink-grace-timer)
              (setq jit-lock--antiblink-grace-timer nil)))
           (same-line
-           ;; In same line, but no state change, leave everything as it was
+           ;; In same line, but no state change, leave everything as it was.
            )
           (t
-           ;; Left the line somehow or customized feature away, etc
+           ;; Left the line somehow or customized feature away, etc.;
            ;; kill timer if running, resume normal operation.
            (when jit-lock--antiblink-grace-timer
              ;; Do refontify immediately, adding a small delay.  This
-             ;; makes sense because it remark somehow that we are
+             ;; makes sense because it signals somehow that we are
              ;; leaving the unstable state.
              (jit-lock-context-fontify)
              (cancel-timer jit-lock--antiblink-grace-timer)
              (setq jit-lock--antiblink-grace-timer nil))))
-    ;; Update variables (and release the marker)
+    ;; Update variables (and release the marker).
     (set-marker jit-lock--antiblink-line-beginning-position nil)
     (setq jit-lock--antiblink-line-beginning-position new-l-b-p
           jit-lock--antiblink-string-or-comment new-s-o-c)))