scratch/jit-lock-antiblink-cleaned-up 38b5ad6 5/6: Adjust jit-lock-antiblink documentation again

[João Távora]

branch: scratch/jit-lock-antiblink-cleaned-up
commit 38b5ad638fea651bef568e713e26f4b506e56ee6
Author: João Távora <address@hidden>
Commit: João Távora <address@hidden>

    Adjust jit-lock-antiblink documentation again
    
    * etc/NEWS: Mention default value of jit-lock-antiblink-grace.
    
    * lisp/jit-lock.el (jit-lock-antiblink-grace): Simplifify docstring.
    (jit-lock--antiblink-post-command): Rework comment.  Cleanup
    whitespace.
---
 etc/NEWS         |  8 ++++----
 lisp/jit-lock.el | 33 +++++++++++++++------------------
 2 files changed, 19 insertions(+), 22 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index bcec466..55c861c 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -628,10 +628,10 @@ current and the previous or the next line, as before.
 
 ---
 ** New customizable variable 'jit-lock-antiblink-grace'.
-When adding strings to source code, this helps avoid
-\"blinking\", an unwanted oscillation of certain regions between
-string and non-string fontification.
-
+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 deactivate.
 
 
 * Changes in Specialized Modes and Packages in Emacs 27.1
diff --git a/lisp/jit-lock.el b/lisp/jit-lock.el
index 23afb53..c896c9d 100644
--- a/lisp/jit-lock.el
+++ b/lisp/jit-lock.el
@@ -124,18 +124,18 @@ The value of this variable is used when JIT Lock mode is 
turned on."
   :group 'jit-lock)
 
 (defcustom jit-lock-antiblink-grace 2
-  "Idle time after which to refontify due to unterminated strings.
-If the user creates a temporarily unterminated string up to the
-end of the current line, that part of the line is fontified after
-`jit-lock-context-time', but an extended idle \"grace\" period of
-this many seconds is granted before deciding it is a multi-line
-string and fontifying the remainder of the buffer accordingly.
-When adding strings to source code, this helps avoid
-\"blinking\", an unwanted oscillation of certain regions between
-string and non-string fontification.  If nil, there is no grace
-period."
-  :type '(number :tag "seconds")
-  :group 'jit-lock)
+  "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."
+  :type '(choice (const :tag "never" nil)
+                (number :tag "seconds"))
+  :group 'jit-lock
+  :version "27.1")
 
 (defcustom jit-lock-defer-time nil ;; 0.25
   "Idle time after which deferred fontification should take place.
@@ -178,8 +178,6 @@ If nil, contextual fontification is disabled.")
   "Last line beginning position after last command (a marker).")
 (defvar jit-lock--antiblink-string-or-comment nil
   "Non-nil if in string or comment after last command (a boolean).")
-
-
 
 ;;; JIT lock mode
 
@@ -734,14 +732,13 @@ will take place when text is fontified stealthily."
            ;; kill timer if running, resume normal operation.
            (when jit-lock--antiblink-grace-timer
              ;; Do refontify immediately, adding a small delay.  This
-             ;; is per Lars' request, and it makes sense because we
-             ;; should remark somehow that we are leaving the unstable
-             ;; state.
+             ;; makes sense because it remark 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
-    (setq jit-lock--antiblink-line-beginning-position   new-l-b-p
+    (setq jit-lock--antiblink-line-beginning-position new-l-b-p
           jit-lock--antiblink-string-or-comment new-s-o-c)))
 
 (provide 'jit-lock)