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

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

> > The doc string does not describe the default behavior: select another
> > window in the same frame, if there is one.
> >
> > The doc string refers to the doc for `next-window', for the reader to
> > find out what ALL-FRAMES does - even for the default, nil, case.
> >
> > It is fine to refer to `next-window' for ALL-FRAMES (e.g. for full
> > understanding and for non-interactive use).  But surely the default
> > interactive behavior should be described.
> 
> 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.

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 is simple to make this immediately clear to users, and we
should do so.