On Wed, Dec 13, 2017 at 8:37 AM, Stefan Monnier <monnier@iro.umontreal.ca>
wrote:

> > `select-window' is a function with immediate effect so we can give it a
> > self-contained doc-string and description.
> [...]
> > So I think that people who need information about how to raise a frame
> > or giving it input focus should look into the Elisp manual.
>
> I don't think select-window should explain what
> select-frame-set-input-focus does, indeed.  But I think it'd be OK for
> it to make it clear that it doesn't directly affect focus, with a link
> to another function that does.
>

​Agreed.  It is natural for people to start programming things in Emacs
with a single frame and multiple windows.  As they expand their knowledge
to multiple frames and selecting a window in another frame, they'll want to
know the extent of what select-window handles and what it doesn't.  Their
could be simple explanations and references on input focus like:

Although this selects the window's frame, it does not alter the frame's
position in the window stack (see `raise-frame') nor does it direct input
focus to that frame.
To do both of those at once, see `select-frame-set-input-focus'.

Bob
​