From 2a861124e89d7a29b19bb9a6f22e962c37444212 Mon Sep 17 00:00:00 2001
From: Eli Zaretskii <eliz@gnu.org>
Date: Sat, 6 Jan 2024 11:15:31 +0200
Subject: [PATCH] ; Improve documentation of 'buffer-match-p'

* doc/lispref/buffers.texi (Buffer List):
* doc/lispref/windows.texi (Choosing Window): Add caveats for
calling 'buffer-match-p' too early, when CONDITION is
'derived-mode' or 'major-mode'.  (Bug#68081)
---
 doc/lispref/buffers.texi | 13 +++++++++----
 doc/lispref/windows.texi | 14 +++++++++-----
 2 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index b7047a68856..f67a954edc5 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -959,7 +959,7 @@ 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 the specified @code{condition}.  Optional third argument
+satisfies the specified @var{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{}
@@ -987,10 +987,15 @@ Satisfied if @emph{any} condition in @var{conds} satisfies
 Satisfied if @emph{all} the conditions in @var{conds} satisfy
 @code{buffer-match-p}, with the same buffer and @code{arg}.
 @item derived-mode
-Satisfied if the buffer's major mode derives from @var{expr}.
+Satisfied if the buffer's major mode derives from @var{expr}.  Note
+that this condition might fail to report a match if
+@code{buffer-match-p} is invoked before the major mode of the buffer
+has been established.
 @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.  Note that this
+condition might fail to report a match if @code{buffer-match-p} is
+invoked before the major mode of the buffer has been established.
 @end table
 @item t
 Satisfied by any buffer.  A convenient alternative to @code{""} (empty
@@ -1000,7 +1005,7 @@ string) or @code{(and)} (empty conjunction).
 
 @defun match-buffers condition &optional buffer-list arg
 This function returns a list of all buffers that satisfy the
-@code{condition}.  If no buffers match, the function returns
+@var{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
diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi
index 39e6d1386c6..d72da704f13 100644
--- a/doc/lispref/windows.texi
+++ b/doc/lispref/windows.texi
@@ -2629,11 +2629,15 @@ 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 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-@code{nil} value, then
-@code{display-buffer} uses the corresponding display action to display
-the buffer.
+actions.  Each condition is passed to @code{buffer-match-p}
+(@pxref{Buffer List}), along with the buffer name and the @var{action}
+argument passed to @code{display-buffer}.  If it returns a
+non-@code{nil} value, then @code{display-buffer} uses the
+corresponding display action to display the buffer.  Caveat: if you
+use @code{derived-mode} or @code{major-mode} as condition,
+@code{buffer-match-p} could fail to report a match if
+@code{display-buffer} is called before the major mode of the buffer is
+set.
 @end defopt
 
 @defopt display-buffer-base-action
-- 
2.39.2