; Fix last change

* lisp/pulse.el (pulse-faces, pulse-face-duration):
* etc/NEWS: Fix documentation of last change.  (Bug#77715)

(cherry picked from commit 3b2b0424cf9458d8f59b283139f46e1515989df3)

diff --git a/lisp/pulse.el b/lisp/pulse.el
index ddae9c049402a7edafc7c7944bfc71fd2e841b38..b44c7f5d0db1f29605fdbb9c9c0cddc01916b1a2 100644 (file)
--- a/lisp/pulse.el
+++ b/lisp/pulse.el
@@ -228,32 +228,34 @@ Only pulses the line if `pulse-command-advice-flag' is non-nil."
     (pulse-momentary-highlight-one-line (point))))
 
 ;;; Pulse faces
-;; Functions for pulse any defined face.
+;; Functions for pulsing any defined face(s).
 (require 'face-remap)
 
 (defcustom pulse-face-duration pulse-delay
-  "Time (in seconds) used for pulse face duration."
+  "Time (in seconds) used for `pulse-faces' duration."
   :type 'number
   :group 'pulse
   :version "31.1")
 
-;; FIXME: The pulse smooth effect cannot be archieved here due
-;;        the face remaping will not work well for that.
+;; FIXME: The pulse's smooth effect cannot be achieved here because
+;;        the face-remaping will not work well for that.
 (defun pulse-faces (faces &optional with-face)
-  "Pulse FACES with face WITH-FACE (if defined) briefly.
-FACES must be a list of faces to pulse.
-WITH-FACE is optional, it can be a defined face or a list of face
-properties to apply."
+  "Briefly pulse FACES by using attributes of face WITH-FACE (if defined).
+FACES should be a list of faces to pulse.
+WITH-FACE is optional, it can be a defined face or a list
+of face properties to apply.  If nil or omitted, it defaults
+to `pulse-highlight-face'."
   (when-let* (((numberp pulse-face-duration)) ; Ensure time is a number
               (with-face (or with-face 'pulse-highlight-face))
               (in-buffer (current-buffer))
               (cookies (mapcar (lambda (f)
                                  (if (consp with-face)
-                                     (apply #'face-remap-add-relative f with-face)
+                                     (apply #'face-remap-add-relative
+                                            f with-face)
                                    (face-remap-add-relative f with-face)))
                                faces)))
-    ;; Use run-with-timer if the duration is very long for not blocking
-    ;; emacs, otherwise fallback to sleep-for.
+    ;; Use run-with-timer if the duration is very long, so as to avoid
+    ;; blocking emacs; otherwise fall back to 'sleep-for'.
     (if (> pulse-face-duration 0.1)
         (run-with-timer pulse-face-duration 0
                         (lambda ()
@@ -264,7 +266,7 @@ properties to apply."
                                 (mapc #'face-remap-remove-relative cookies)))))
       (unwind-protect
           (progn
-            ;; redisplay for apply the face remap
+            ;; Redisplay to apply the face remapping.
             (redisplay)
             (sleep-for pulse-face-duration))
         (mapc #'face-remap-remove-relative cookies)))))