bug#19682: 25.0.50; `other-window' doc string should say that by default it selects win in same frame

[Eli Zaretskii <eliz@gnu.org>]

> Date: Sun, 25 Jan 2015 09:12:23 -0800 (PST)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 19682@debbugs.gnu.org
> 
> > The doc string says:
> > 
> >   This function uses `next-window' for finding the window to
> >   select.  The argument ALL-FRAMES has the same meaning as in
> >   `next-window', but the MINIBUF argument of `next-window' is
> >   always effectively nil.
> > 
> > This is a very clear invitation to read the documentation of
> > 'next-window', if the reader cares about which window will be
> > selected.  If the reader indeed goes there, she will find there the
> > details of what you wanted her to know.
> > 
> > OTOH, many uses of 'other-window' don't really care about the order
> > and the candidates, in which case that argument is of no importance
> > for them.
> > 
> > So I see no reason to think this doc strings lacks something
> > important.
> 
> The default interactive behavior should be described clearly,
> as the first thing in the doc string.  Users, especially Lisp
> users, can read further to discover more information about
> possible argument values and behavior.

We are in violent agreement about this.  It's just that I think the
current doc string does precisely that.

> But the first thing that needs to be said, very clearly, and
> preferably without any reference to arguments or other doc
> strings, is what the default behavior is.

It already does.  It just doesn't divulge _all_ the details about the
selection of the "other" window.