Re: master c3ab8f1: Improve buffer-match-p documentation

[Philip Kaludercic]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Philip Kaludercic <philipk@posteo.net>
>> Cc: emacs-devel@gnu.org
>> Date: Sat, 16 Apr 2022 09:53:26 +0000
>> 
>> Eli Zaretskii <eliz@gnu.org> writes:
>> 
>> >> +** New function 'buffer-match-p'
>> >> +Check if a buffer matches a condition, specified using a DSL.
>> >
>> > A "DSL"? what's that?  We don't have that acronym anywhere else in
>> > Emacs, AFAICS.  Please make that entry more self-explanatory.
>> 
>> It is supposed to mean "Domain Specific Language".  I never noticed that
>> it wasn't used anywhere else, so sorry about that.  Then again I wasn't
>> sure how else to put it.  What about
>> 
>>      Can be used to check if buffers satisfy a possibly complex
>>      condition, [giving a few examples]
>
> Just "satisfies some conditions" (with examples) should be fine, IMO.
>
>> > Since buffer-match-p is not documented in the manual, I think this
>> > change is for the worse, as it leaves CONDITIONS undocumented.  Or am
>> > I missing something?
>> 
>> No, I haven't written that yet.  This should best be documented in
>> lispref/buffers.texi, right? 
>
> Probably in "Buffer List", yes.
>
>> >> -(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'."
>> >
>> > I fixed some minor issues with the modified doc string, but that still
>> > leaves one question unanswered: what does this function return if no
>> > alist entry satisfies buffer-match-p?  That should be documented.
>> 
>>   ... If no entry is found, nil is returned?
>
> That's fine, but please avoid passive tense.  Something like
>
>   If no matching entry is found in ALIST, return nil.

Before I push something I should fix, I'll attach my proposed changes
here:

>From 4aa5fecf89d0aae084eb12ba5b2651b6fd9dc991 Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk@posteo.net>
Date: Sun, 17 Apr 2022 01:11:06 +0200
Subject: [PATCH] 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.
---
 doc/lispref/buffers.texi | 41 ++++++++++++++++++++++++++++++++++++++++
 etc/NEWS                 |  6 +++++-
 lisp/window.el           |  3 ++-
 3 files changed, 48 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/buffers.texi b/doc/lispref/buffers.texi
index 1fe5a60b35..0004f255fe 100644
--- a/doc/lispref/buffers.texi
+++ b/doc/lispref/buffers.texi
@@ -953,6 +953,47 @@ Buffer List
 infinite recursion.
 @end defvar
 
+@defun buffer-match-p condition buffer-or-name arg
+This function can be used to check if a buffer designated by
+@code{buffer-or-name} satisfies a @code{condition}.  An optional third
+argument @code{arg} can be passed on to predicate functions.  A
+predicate can be one of the following:
+@itemize @bullet{}
+@item
+A string containing a regular expression.  The buffer satisfies the
+predicate if the regular expression matches the buffer name.
+@item
+A function that is passed the buffer, and is satisfied if the function
+returns a non-nil value.  The first argument is always the buffer, and
+if the function accepts two arguments (as per @code{func-arity}), the
+third argument to @code{buffer-match-p} will be passed on to the
+predicate function.
+@item
+A cons-cell @code{(TYPE . DATA)} where @code{TYPE} is one of
+@table @code
+@item not
+Satisfied if @code{DATA} doesn't satisfy @code{buffer-match-p} with
+the same buffer and @code{arg}.
+@item or
+Satisfied if @code{DATA} is a list and @emph{any} condition if
+@code{DATA} satisfies @code{buffer-match-p}, with the same buffer and
+@code{arg}.
+@item and
+Satisfied if @code{DATA} is a list and @emph{all} condition if
+@code{DATA} satisfies @code{buffer-match-p}, with the same buffer and
+@code{arg}.
+@end table
+@end itemize
+@end defun
+
+@defun match-buffers condition 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.  Optionally, a third argument
+@code{arg} is passed on to @code{buffer-match-p}.
+@end defun
+
 @node Creating Buffers
 @section Creating Buffers
 @cindex creating buffers
diff --git a/etc/NEWS b/etc/NEWS
index 14d970fe11..fb26ca64f8 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1493,7 +1493,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
diff --git a/lisp/window.el b/lisp/window.el
index ea90995541..b7503ac999 100644
--- a/lisp/window.el
+++ b/lisp/window.el
@@ -7499,7 +7499,8 @@ display-buffer-assq-regexp
   "Retrieve ALIST entry corresponding to BUFFER-NAME.
 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'."
+form of the action argument passed to `display-buffer'.
+If no matching entry is found in ALIST, return nil."
   (catch 'match
     (dolist (entry alist)
       (when (buffer-match-p (car entry) buffer-or-name action)
-- 
2.30.2

-- 
        Philip Kaludercic