diff options
author | Eli Zaretskii <eliz@gnu.org> | 2023-04-10 12:30:23 +0300 |
---|---|---|
committer | Eli Zaretskii <eliz@gnu.org> | 2023-04-10 12:30:23 +0300 |
commit | 2445100d7d6dd698d561e554a35fe2c9f87edc9f (patch) | |
tree | 3c4ccdad3f1b9f7ab4084f9482960a9ff4ebfdc0 | |
parent | d4d0da96f0b474ccab64349c12d5a7638b81bbdb (diff) | |
download | emacs-2445100d7d6dd698d561e554a35fe2c9f87edc9f.tar.gz |
; 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'.
-rw-r--r-- | doc/lispref/buffers.texi | 24 | ||||
-rw-r--r-- | 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) |