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

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

> > > The order is unspecified, which means the caller should not
> > > depend on it.  I don't think there's anything wrong with that;
> > > do you?
> >
> > Well, it's certainly the prerogative of designers to decide that
> > the order is undefined and that users cannot depend on it.  In
> > that case, you can close the bug now.
> >
> > But as one user I'm disappointed.  I was hoping for a usable
> > window order.
> 
> It's the order of traversing the window tree depth-first (as
> described in the ELisp manual under "Cyclic Window Ordering").

If so, then the order is not undefined.  (It's a design decision
whether Emacs wants to commit to supporting this order or just
tell users that the order is undefined, keeping its options open.)

> I don't see how saying that would be of any help to users of this
> function.

Well, it apparently won't help me in my quest for a chronological
ordering of windows for the same buffer by access time.

But I think it would be helpful to tell users that the order is
the same as that described in `Cyclic Window Ordering'.

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

Perhaps I'm missing something.  And I will leave it up to you to
decide what, if anything, should be said about the order.  Thanks
for thinking about it.