Further improve buffer-match-p related documentation

* doc/lispref/buffers.texi (Buffer List): Add entries for
* buffer-match-p and match-buffers
* etc/NEWS: Give examples for buffer-match-p conditions
* lisp/window.el (display-buffer-assq-regexp): Mention what happens
when no entry in the alist satisfies a condition.

2 files changed, 52 insertions, 4 deletions

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 1fe5a60b356..d8cf3d7919b 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -953,15 +953,59 @@ with a @code{nil} @var{norecord} argument since this may lead to
 infinite recursion.
 @end defvar
 
+@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:
+@itemize @bullet{}
+@item
+A string, interpreted as a regular expression.  The buffer
+satisfies the condition if the regular expression matches the buffer
+name.
+@item
+A predicate function, which should return non-@code{nil} if the buffer
+matches.  If the function expects one argument, it is called with
+@var{buffer-or-name} as the argument; if it expects 2 arguments, the
+first argument is @var{buffer-or-name} and the second is @var{arg}
+(or @code{nil} if @var{arg} is omitted).
+@item
+A cons-cell @code{(@var{oper} . @var{expr})} where @var{oper} is one
+of
+@table @code
+@item not
+Satisfied if @var{expr} doesn't satisfy @code{buffer-match-p} with
+the same buffer and @code{arg}.
+@item or
+Satisfied if @var{oper} is a list and @emph{any} condition if
+@var{expr} satisfies @code{buffer-match-p}, with the same buffer and
+@code{arg}.
+@item and
+Satisfied if @var{oper} is a list and @emph{all} condition if
+@var{expr} satisfies @code{buffer-match-p}, with the same buffer and
+@code{arg}.
+@end table
+@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.
+@end defun
+
 @node Creating Buffers
 @section Creating Buffers
 @cindex creating buffers
 @cindex buffers, creating
 
   This section describes the two primitives for creating buffers.
-@code{get-buffer-create} creates a buffer if it finds no existing buffer
-with the specified name; @code{generate-new-buffer} always creates a new
-buffer and gives it a unique name.
+@code{get-buffer-create} creates a buffer if it finds no existing
+buffer with the specified name; @code{generate-new-buffer} always
+creates a new buffer and gives it a unique name.
 
   Both functions accept an optional argument @var{inhibit-buffer-hooks}.
 If it is non-@code{nil}, the buffer they create does not run the hooks
diff --git a/etc/NEWS b/etc/NEWS
index 0245ec8c689..071fdd7aee9 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1548,7 +1548,11 @@ This hook is run before 'x-popup-menu' is about to display a
 deck-of-cards menu on screen.
 
 ** New function 'buffer-match-p'
-Check if a buffer matches a condition, specified using a DSL.
+Check if a buffer satisfies some condition.  Some examples for
+conditions can be regular expressions that match a buffer name, a
+cons-cell like (major-mode . shell-mode) that matches any buffer where
+major-mode is shell-mode or a combined with a condition like (and
+"\\`\\*.+\\*\\'" (major-mode . special-mode)).
 
 ** New function 'match-buffers'
 Use 'buffer-match-p' to gather a list of buffers that match a