emacs-29 2445100d7d6: ; Improve documentation of 'match-buffers'

[Eli Zaretskii]

branch: emacs-29
commit 2445100d7d6dd698d561e554a35fe2c9f87edc9f
Author: Eli Zaretskii <eliz@gnu.org>
Commit: Eli Zaretskii <eliz@gnu.org>

    ; Improve documentation of 'match-buffers'
    
    * doc/lispref/buffers.texi (Buffer List):
    * lisp/subr.el (match-buffers): Fix documentation of
    'buffer-match-p' and 'match-buffers'.
---
 doc/lispref/buffers.texi | 24 +++++++++++++-----------
 lisp/subr.el             | 13 +++++++------
 2 files changed, 20 insertions(+), 17 deletions(-)

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index b56006e5aa9..86c47ae7310 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -959,9 +959,9 @@ infinite recursion.
 
 @defun buffer-match-p condition buffer-or-name &optional arg
 This function checks if a buffer designated by @code{buffer-or-name}
-satisfies a @code{condition}.  Optional third argument @var{arg} is
-passed to the predicate function in @var{condition}.  A condition can
-be one of the following:
+satisfies the specified @code{condition}.  Optional third argument
+@var{arg} is passed to the predicate function in @var{condition}.  A
+valid @var{condition} can be one of the following:
 @itemize @bullet{}
 @item
 A string, interpreted as a regular expression.  The buffer
@@ -990,21 +990,23 @@ Satisfied if @emph{all} the conditions in @var{conds} 
satisfy
 Satisfied if the buffer's major mode derives from @var{expr}.
 @item major-mode
 Satisfied if the buffer's major mode is equal to @var{expr}.  Prefer
-using @code{derived-mode} instead when both can work.
+using @code{derived-mode} instead, when both can work.
 @end table
 @item t
 Satisfied by any buffer.  A convenient alternative to @code{""} (empty
-string), @code{(and)} (empty conjunction) or @code{always}.
+string) or @code{(and)} (empty conjunction).
 @end itemize
 @end defun
 
 @defun match-buffers condition &optional buffer-list arg
-This function returns a list of all buffers that satisfy a
-@code{condition}, as defined for @code{buffer-match-p}.  By default
-all buffers are considered, but this can be restricted via the second
-optional @code{buffer-list} argument.  Optional third argument
-@var{arg} will be used by @var{condition} in the same way as
-@code{buffer-match-p} does.
+This function returns a list of all buffers that satisfy the
+@code{condition}.  If no buffers match, the function returns
+@code{nil}.  The argument @var{condition} is as defined in
+@code{buffer-match-p} above.  By default, all the buffers are
+considered, but this can be restricted via the optional argument
+@code{buffer-list}, which should be a list of buffers to consider.
+Optional third argument @var{arg} will be passed to @var{condition} in
+the same way as @code{buffer-match-p} does.
 @end defun
 
 @node Creating Buffers
diff --git a/lisp/subr.el b/lisp/subr.el
index 46dcd97d829..d4428aef765 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -7128,12 +7128,13 @@ CONDITION is either:
     (funcall match (list condition))))
 
 (defun match-buffers (condition &optional buffers arg)
-  "Return a list of buffers that match CONDITION.
-See `buffer-match-p' for details on CONDITION.  By default all
-buffers are checked, this can be restricted by passing an
-optional argument BUFFERS, set to a list of buffers to check.
-ARG is passed to `buffer-match', for predicate conditions in
-CONDITION."
+  "Return a list of buffers that match CONDITION, or nil if none match.
+See `buffer-match-p' for various supported CONDITIONs.
+By default all buffers are checked, but the optional
+argument BUFFERS can restrict that: its value should be
+an explicit list of buffers to check.
+Optional argument ARG is passed to `buffer-match-p', for
+predicate conditions in CONDITION."
   (let (bufs)
     (dolist (buf (or buffers (buffer-list)))
       (when (buffer-match-p condition (get-buffer buf) arg)