bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?

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

> > In the manual?  Where?  I don't see it, so far (in the build I
> > have from 7/31.  I do see that the manual says this, but this
> > speaks only to the meaning of these two arguments - it says
> > nothing about the order of the windows in the returned value.
> >
> >   The arguments MINIBUF and ALL-FRAMES have the same meanings as
> >                 ^^^^^^^^^^^^^^^^^^^^^^
> >   in the function 'next-window' (*note Cyclic Window Ordering::).
> 
> In the cross-referenced node.

It sends you to that node for an entirely different purpose -
not for information about the order of the returned value.  The
xref is even part of the _same sentence_ as the statement about
the args.  It is not a separate sentence telling to go see that
node for more info about the function as a whole.  And it certainly
is not hinting that you will discover there something about the
order of the function's return value.

If I tell you that you can get a great bagel at Schlomo's Deli,
would you expect that you might also get a great car wash there?

> > I meant in the manual.  There is an xref to that node, but it is
> > given only for info about arguments MINIBUF and ALL-FRAMES.
> 
> No, it's not.  It actually tells you that this function traverses
> the window as next-window does.

The xref'd node does.  But the xref is explicitly "given only for
info about arguments MINIBUF and ALL-FRAMES."  A minor change
would make it clear that that node also tells you something about
the order of the return value.  (It would still be better to
document the return value completely in the source node, and send
readers to the xref for _additional_ info.

> Once again, I think this order is random for all practical purposes,
> as far as the caller is concerned.  I was actually surprised to see
> it documented in the manual.

Again, either Emacs decides that it wants to specify nothing
about the order, and says it is unspecified, or it decides it
wants to tell users what the order is (and so commits, to some
extent, to that order, e.g., including for the future).

It's your choice.  What is the design?  Do you want to expose
this as by design, and tell users about it so they can take
advantage of it, or do you want to tell users not to depend
on the currently implemented order?