From: João Távora <joaotavora@gmail.com>
Date: Thu, 26 Oct 2023 21:10:56 +0000 (+0100)
Subject: Rework docstring for completion-lazy-hilit
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=e00728ed5f4409c2dc171d841ff8f25932867774;p=emacs.git

Rework docstring for completion-lazy-hilit

bug#48841, bug#47711

* lisp/minibuffer.el (completion-lazy-hilit): Rework docstring.
---

diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el
index e8f06639df7..b38eb49aba8 100644
--- a/lisp/minibuffer.el
+++ b/lisp/minibuffer.el
@@ -3763,24 +3763,28 @@ than the latter (which has two \"holes\" and three
 one-letter-long matches).")
 
 (defvar-local completion-lazy-hilit nil
-  "If non-nil, request completion lazy hilighting.
+  "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-sorted-completions').  This hints the
-intervening completion styles that they do not need to propertize
-completion strings with the `face' property.
+intervening completion styles that they do not need to
+fontify (i.e. propertize with the `face' property) completion
+strings with highlights of the matching parts.
 
 When doing so, it is the frontend -- not the style -- who becomes
-responsible for `face'-propertizing only the completion strings
-that are meant to be displayed to the user.  This is done by
-calling `completion-lazy-hilit' on each such string, which
-produces the suitably propertized string.
-
-Note that the optimization enabled by variable is only actually
-performed some completions styles.  To others, it is a harmless
-and useless hint.  To author a completion style that takes
-advantage of this, look in the source of
+responsible 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
+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 greedily fontify as usual.  It is still safe for a
+frontend 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'.")
 
 (defvar completion-lazy-hilit-fn nil