Improve documentation of last change

* lisp/hi-lock.el (hi-lock-set-pattern, hi-lock-face-buffer):
Improve the doc strings.  (Bug#32365)

* etc/NEWS:
* doc/emacs/display.texi (Highlight Interactively): Clarify
wording.

3 files changed, 11 insertions, 6 deletions

diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index fe4936d85a1..d9a08b974f6 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -974,9 +974,10 @@ the buffer is loaded.  For example, to highlight all occurrences of
 the word ``whim'' using the default face (a yellow background), type
 @kbd{M-s h r whim @key{RET} @key{RET}}.  Any face can be used for
 highlighting, Hi Lock provides several of its own and these are
-pre-loaded into a list of default values.  While being prompted
-for a face use @kbd{M-n} and @kbd{M-p} to cycle through them.  A prefix
-argument limits the highlighting to the corresponding subexpression.
+pre-loaded into a list of default values.  While being prompted for a
+face use @kbd{M-n} and @kbd{M-p} to cycle through them.  A prefix
+numeric argument limits the highlighting to the corresponding
+subexpression.
 
 @vindex hi-lock-auto-select-face
 Setting the option @code{hi-lock-auto-select-face} to a non-@code{nil}
diff --git a/etc/NEWS b/etc/NEWS
index 5146e756d00..6f23f7ee427 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -720,7 +720,8 @@ UUID at point.
 
 +++
 *** 'highlight-regexp' can now highlight subexpressions.
-The command accepts a prefix argument to choose the subexpression.
+The now command accepts a prefix numeric argument to choose the
+subexpression.
 
 
 * New Modes and Packages in Emacs 27.1
diff --git a/lisp/hi-lock.el b/lisp/hi-lock.el
index 23820cda587..08b58117dd0 100644
--- a/lisp/hi-lock.el
+++ b/lisp/hi-lock.el
@@ -433,7 +433,8 @@ highlighting will not update as you type."
   "Set face of each match of REGEXP to FACE.
 Interactively, prompt for REGEXP using `read-regexp', then FACE.
 Use the global history list for FACE.  Limit face setting to the
-corresponding SUBEXP of REGEXP.
+corresponding SUBEXP (interactively, the prefix argument) of REGEXP.
+If SUBEXP is omitted or nil, the entire REGEXP is highlighted.
 
 Use Font lock mode, if enabled, to highlight REGEXP.  Otherwise,
 use overlays for highlighting.  If overlays are used, the
@@ -689,7 +690,9 @@ with completion and history."
     (intern face)))
 
 (defun hi-lock-set-pattern (regexp face &optional subexp)
-  "Highlight SUBEXP of REGEXP with face FACE."
+  "Highlight SUBEXP of REGEXP with face FACE.
+If omitted or nil, SUBEXP defaults to zero, i.e. the entire
+REGEXP is highlighted."
   ;; Hashcons the regexp, so it can be passed to remove-overlays later.
   (setq regexp (hi-lock--hashcons regexp))
   (setq subexp (or subexp 0))