master 14f0b6331d2 1/2: ; Minor documentation fixes

[Eli Zaretskii]

branch: master
commit 14f0b6331d2248476ab5fe44bb1217327cf6724a
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Minor documentation fixes
    
    * etc/NEWS:
    * lisp/minibuffer.el (completion-lazy-hilit)
    (completion-lazy-hilit-fn, completion-lazy-hilit): Fix recently
    added documentation.
---
 etc/NEWS           | 11 ++++++-----
 lisp/minibuffer.el | 48 +++++++++++++++++++++++-------------------------
 2 files changed, 29 insertions(+), 30 deletions(-)

diff --git a/etc/NEWS b/etc/NEWS
index b9a1c3dd572..767e4c27b43 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1280,11 +1280,12 @@ If non-nil, this variable contains a keymap of menu 
items that are
 displayed along tool bar items inside 'tool-bar-map'.
 
 ** New variable 'completion-lazy-hilit'.
-Completion-presenting frontends may bind this variable non-nil around
-calls to functions such as `completion-all-completions'.  This hints
-at the underlying completion styles to skip eager fontification of
-completion candidates, which increases performance.  Frontends then
-use the 'completion-lazy-hilit' function to fontify just in time.
+Lisp programs that present completion candidates may bind this
+variable non-nil around calls to functions such as
+'completion-all-completions'.  This tells the underlying completion
+styles to skip eager fontification of completion candidates, which
+improves performance.  Such a Lisp program can then use the
+'completion-lazy-hilit' function to fontify candidates just in time.
 
 ** Functions and variables to transpose sexps
 
diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index ca2b25415f1..8d662fafb9e 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -3799,41 +3799,39 @@ than the latter (which has two \"holes\" and three
 one-letter-long matches).")
 
 (defvar completion-lazy-hilit nil
-  "If non-nil, request completion lazy highlighting.
-
-Completion-presenting frontends may opt to bind this variable to
-non-nil value in the context of completion-producing calls (such
-as `completion-all-completions').  This hints the intervening
-completion styles that they do not need to
-fontify (i.e. propertize with a `face' property) completion
-strings with highlights of the matching parts.
-
-When doing so, it is the frontend -- not the style -- who becomes
-responsible for this fontification.  The frontend binds this
-variable to non-nil, and calls the function with the same name
-`completion-lazy-hilit' on each completion string that is to be
+  "If non-nil, request lazy highlighting of completion candidates.
+
+Lisp programs (a.k.a. \"front ends\") that present completion
+candidates may opt to bind this variable to a non-nil value when
+calling functions (such as `completion-all-completions') which
+produce completion candidates.  This tells the underlying
+completion styles that they do not need to fontify (i.e.,
+propertize with the `face' property) completion candidates in a
+way that highlights the matching parts.  Then it is the front end
+which presents the candidates that becomes responsible for this
+fontification.  The front end does that by calling the function
+`completion-lazy-hilit' on each completion candidate that is to be
 displayed to the user.
 
 Note that only some completion styles take advantage of this
 variable for optimization purposes.  Other styles will ignore the
 hint and fontify eagerly as usual.  It is still safe for a
-frontend to call `completion-lazy-hilit' in these situations.
+front end to call `completion-lazy-hilit' in these situations.
 
-To author a completion style that takes advantage see
-`completion-lazy-hilit-fn' and look in the source of
-`completion-pcm--hilit-commonality'.")
+To author a completion style that takes advantage of this variable,
+see `completion-lazy-hilit-fn' and `completion-pcm--hilit-commonality'.")
 
 (defvar completion-lazy-hilit-fn nil
-  "Function set by lazy-highlighting completions styles.
-When a given style wants to enable support for
-`completion-lazy-hilit' (which see), that style should set this
-variable to a function of one argument, a fresh string to be
-displayed to the user.  The function is responsible for
-destructively propertizing the string with a `face' property.")
+  "Fontification function set by lazy-highlighting completions styles.
+When a given style wants to enable support for `completion-lazy-hilit'
+\(which see), that style should set this variable to a function of one
+argument.  It will be called with a completion candidate, a string, to
+be displayed to the user, and should destructively propertize the string
+with the `face' property.")
 
 (defun completion-lazy-hilit (str)
-  "Return a copy of completion STR that is `face'-propertized.
-See documentation for variable `completion-lazy-hilit' for more
+  "Return a copy of completion candidate STR that is `face'-propertized.
+See documentation of the variable `completion-lazy-hilit' for more
 details."
   (if (and completion-lazy-hilit completion-lazy-hilit-fn)
       (funcall completion-lazy-hilit-fn (copy-sequence str))