bug#19571: 25.0.50; `display-buffer-alist': ALIST is completely undefined

[Drew Adams <drew.adams@oracle.com>]

> > ALIST is mentioned only here:
> >
> >  ACTION is a cons cell (FUNCTION . ALIST), where FUNCTION is a
> >   function or a list of functions.  Each such function should
> >   accept two arguments: a buffer to display and an alist of the
> >   same form as ALIST.  See `display-buffer' for details.
> >
> > "of the same form as ALIST"?  Really?  What form is that?  Where is
> > *anything* said about the form of ALIST?
> 
> It's an alist.  And you are referred to the documentation of
> 'display-buffer' for details.  I see nothing wrong with that.

No, you are referred to `display-buffer' for ACTION - for info about
everything in the ACTION paragraph.  Nothing says that the ALIST here
is related to the ALIST mentioned for `display-buffer', at all.
Or if it is related somehow, nothing says how it is related.

The ALIST mentioned for `display-buffer' is described in its doc
string only as "an arbitrary association list (alist)."  Arbitrary.
That doesn't jibe well with "of the same form as ALIST" in the
description of `display-buffer-alist', which suggests that the ALIST
mentioned for `display-buffer-alist' has some particular form,
unspecified here.

Or else it suggests that, whatever the form an ALIST for
`display-buffer-alist' might have in any given concrete instance,
the alist to be accepted as arg to each FUNCTION must have that
same form.

In that case, we are left wondering, not about some predefined but
unspecified form that ALIST must have, but rather what could possibly
even be meant by the "form" that it takes concretely.  IOW, we wonder
what kind of form conformance is required for the alist arg that
FUNCTION must accept - in what way must it agree with the "form" of
ALIST?

My guess is that, at the very least, there is some misleading text
to remove here. The description now is a puzzle.

If there is nothing to say about ALIST, so that it is simply an
"arbitrary" alist, then I'd say that nothing more should be said
about it - certainly nothing suggesting that it might need to
have a particular form.

If there is some agreement ("form" or otherwise) that must be had
between ALIST and the alist arg accepted by FUNCTION, then please
spell out what is meant by that.  For example, if the keys in the
alist accepted by FUNCTION must be a subset of the keys in the
actual ALIST for `display-buffer-alist', then say that.  (That's
just a made-up example - I have no idea what the real constraint
being suggested here might be.)

But do with the doc string what you like.  If you find it perfectly
clear, more power to you.  I'm just reporting that I find it
confusing and not so helpful.  HTH.