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

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

> > The doc string says: "Windows are scanned starting with the
> > selected window."  What does that mean?  Scanned?  How so?
> > In what order are they scanned (besides starting with selected)?
> > And how is the scanning used?
> 
> I replaced that sentence with this one:
> 
>   If the selected window displays BUFFER-OR-NAME, it will be the
>   first in the resulting list.
> 
> Do you see any issues left after that change?  (I don't.)
> 
> > Please update both the doc string and (elisp) `Buffers and
> > Windows' to tell us what order the list is in.
> 
> 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.  In fact, I was hoping for something similar to
`buffer-list' - hoping that users would get a list of the windows
(displaying a particular buffer) in order of their last use.

I know no way to obtain such a list, but if there is one, please
be so kind as to let me know.  `walk-windows' etc. go through
windows in their "structural" order, but how can I tell, given
a list of windows showing a given buffer, which were last used
after which others?

Yes, my question is outside the scope of this bug (if the list
`get-buffer-window-list' has no order we can depend on or even
if its order is unrelated to the chronological order of access).

Thanks for fixing the doc string.