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

Previous Next

Full log

View this message in rfc822 format

From: Drew Adams <drew.adams <at> oracle.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Drew Adams <drew.adams <at> oracle.com>
Cc: 21305-done <at> debbugs.gnu.org
Subject: bug#21305: 25.0.50; `get-buffer-window-list' doc - what order?
Date: Fri, 21 Aug 2015 08:28:18 -0700 (PDT)

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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.