bug#12181: 24.1.50; doc of `switch-to-buffer'

[Drew Adams]

The doc, in both the doc string and the Elisp manual, is not clear.
 
It says that the function displays the buffer in the selected window.
But later it says that it might display it in another window or it might
raise an error and not display it at all.
 
The description should be reworded to say that it generally _tries_ to
display the buffer in the selected window.  Otherwise it just sounds
contradictory.
 
Note the evolution:
 
Emacs prior to Emacs 23: We just said that it displayed the buffer in
the selected window.  (We actually said "current" window - back then we
used both "selected" and "current" for both buffers and windows.)
 
Emacs 23: We said the same thing, but we added that if the selected
window is a minibuffer window or is dedicated then we just call
`pop-to-buffer'.  Already that is dodging things a bit and sending the
user off to read about `pop-to-buffer', which itself is complicated
(even if clear).
 
Emacs 24: We added argument FORCE-SAME-WINDOW and complicated the
description some more: it's like Emacs 23, but non-nil FORCE-SAME-WINDOW
raises an error if it cannot be displayed in the selected window.
 
The Emacs 24 description is actually less clear because it does not
refer the reader to the doc for `pop-to-buffer', which doc explains in
detail what happens.  Now, all the reader learns is that the buffer "may
be displayed in another window".  May be?  Under what circumstances?
Another window?  What other window?  Those things were clearer in the
Emacs 23 doc because of the explanation of `pop-to-buffer'.
 
This is all OK in general, but the various possibilities need to be tied
together better.  The description sort of reflects the implementation as
having been a history of patches.
 
It will help to say at the outset that the function _tries_ to use the
selected window.  Then you can speak to what happens if it cannot.  That
"what" should be detailed clearly, or it can refer to functions etc.
whose doc will explain clearly just what happens (as was true in the
Emacs 23 case, where readers could read about `pop-to-buffer').
 

In GNU Emacs 24.1.50.1 (i386-mingw-nt5.1.2600)
 of 2012-08-08 on DANI-PC
Bzr revision: 109511 michael.albinus@gmx.de-20120808134045-t26l1voivvzfypey
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.7) --no-opt --enable-checking --cflags
 -I../../libs/libxpm-3.5.8/include -I../../libs/libxpm-3.5.8/src
 -I../../libs/libpng-1.4.10 -I../../libs/zlib-1.2.6
 -I../../libs/giflib-4.1.4-1/include -I../../libs/jpeg-6b-4/include
 -I../../libs/tiff-3.8.2-1/include
 -I../../libs/libxml2-2.7.8-w32-bin/include/libxml2
 -I../../libs/gnutls-3.0.16/include
 -I../../libs/libiconv-1.14-2-mingw32-dev/include'