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

[Drew Adams]

> > But I think it would be helpful to tell users that the order is
> > the same as that described in `Cyclic Window Ordering'.
> 
> What can the users do with that information?  (It is already in the
> ELisp manual; I'm talking about the doc string here.)

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::).  Note
  that the ALL-FRAMES argument does _not_ behave exactly like in
  'get-buffer-window'. 

> > > Describing the order would require a non-trivial amount of text,
> > > so without a good reason, I don't think we should add it.
> >
> > How is it more difficult than saying that the order is the same as
> > that specified in `Cyclic Window Ordering', and xreffing that
> > node?
> 
> I consider references to the manual in doc strings a bad habit.

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.  It would
be helpful, I think, to explicitly say that the order of the windows
in the return value (a) starts with the selected window (which you
have added) and (b) follows the order cyclic window ordering.