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

[Eli Zaretskii]

> 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.