From c3ab8f188ef801ba2a8227a0732a75adeea315ab Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk@posteo.net>
Date: Fri, 15 Apr 2022 21:12:56 +0200
Subject: [PATCH] Improve buffer-match-p documentation

* doc/lispref/windows.texi (Choosing Window): Document that
buffer-match-p is used by display-buffer-alist.
* etc/NEWS: Mention buffer-match-p and match-buffers.
* lisp/window.el (display-buffer-alist): Update documentation as for
display-buffer-assq-regexp.
(display-buffer-assq-regexp): Rename buffer-name to buffer-or-name.
(display-buffer): Pass the buffer directly to
display-buffer-assq-regexp,.
---
 doc/lispref/windows.texi | 12 +++++-------
 etc/NEWS                 |  7 +++++++
 lisp/window.el           | 18 +++++++++---------
 3 files changed, 21 insertions(+), 16 deletions(-)

diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 43f222d57ff..abc8adae836 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -2596,13 +2596,11 @@ default value is an empty display action, i.e., @w{@code{(nil . nil)}}.
 
 @defopt display-buffer-alist
 The value of this option is an alist mapping conditions to display
-actions.  Each condition may be either a regular expression matching a
-buffer name or a function that takes two arguments: a buffer name and
-the @var{action} argument passed to @code{display-buffer}.  If either
-the name of the buffer passed to @code{display-buffer} matches a
-regular expression in this alist, or the function specified by a
-condition returns non-@code{nil}, then @code{display-buffer} uses the
-corresponding display action to display the buffer.
+actions.  Each condition is passed to @code{buffer-match-p}, along
+with the buffer name and the @var{action} argument passed to
+@code{display-buffer}.  If it returns a non-nil value, then
+@code{display-buffer} uses the corresponding display action to display
+the buffer.
 @end defopt
 
 @defopt display-buffer-base-action
diff --git a/etc/NEWS b/etc/NEWS
index 7d474ac107f..14d970fe11a 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1492,6 +1492,13 @@ them towards or away from each other.
 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.
+
+** New function 'match-buffers'
+Use 'buffer-match-p' to gather a list of buffers that match a
+condition.
+
 ** Text security and suspiciousness
 
 +++
diff --git a/lisp/window.el b/lisp/window.el
index 2da2f8bb2c8..ea909955414 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -7440,9 +7440,9 @@ Its value takes effect before processing the ACTION argument of
 If non-nil, this is an alist of elements (CONDITION . ACTION),
 where:
 
- CONDITION is either a regexp matching buffer names, or a
-  function that takes two arguments - a buffer name and the
-  ACTION argument of `display-buffer' - and returns a boolean.
+ CONDITION is passed to `buffer-match-p', along with the buffer
+  that is to be displayed and the ACTION argument of
+  `display-buffer', to check if ACTION should be used.
 
  ACTION is a cons cell (FUNCTIONS . ALIST), where FUNCTIONS is an
   action function or a list of action functions and ALIST is an
@@ -7495,14 +7495,14 @@ all fail.  It should never be set by programs or users.  See
 `display-buffer'.")
 (put 'display-buffer-fallback-action 'risky-local-variable t)
 
-(defun display-buffer-assq-regexp (buffer-name alist action)
+(defun display-buffer-assq-regexp (buffer-or-name alist action)
   "Retrieve ALIST entry corresponding to BUFFER-NAME.
-This returns the cdr of the alist entry ALIST if either its key
-satisfied a BUFFER-NAME per `buffer-match'.  ACTION should have
-the form of the action argument passed to `display-buffer'."
+This returns the cdr of the alist entry ALIST if key and
+buffer-or-name satisfy `buffer-match-p'.  ACTION should have the
+form of the action argument passed to `display-buffer'."
   (catch 'match
     (dolist (entry alist)
-      (when (buffer-match-p (car entry) buffer-name action)
+      (when (buffer-match-p (car entry) buffer-or-name action)
         (throw 'match (cdr entry))))))
 
 (defvar display-buffer--same-window-action
@@ -7672,7 +7672,7 @@ specified by the ACTION argument."
       ;; Otherwise, use the defined actions.
       (let* ((user-action
 	      (display-buffer-assq-regexp
-	       (buffer-name buffer) display-buffer-alist action))
+	       buffer display-buffer-alist action))
              (special-action (display-buffer--special-action buffer))
 	     ;; Extra actions from the arguments to this function:
 	     (extra-action
-- 
2.39.5