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

​