bug#10879: 24.0.93; doc for `find-file' et al is missing the return value

[Drew Adams]

There are several places in the Emacs source code where `find-file' and
similar commands are used programmatically - typically when defining
other commands, such as `find-file-read-only'.
 
Similarly, 3rd-party code can sometimes use such a command
programmatically, for similar reasons.
 
Code such as the definition of `find-file-read-only' uses the return
value of `find-file'.  The bug is that this return value is not
documented - it should be.
 
The return value is documented only for `find-file-noselect'.  It would
be sufficient for the `find-file' et al doc to say that the return value
of the function is the same as for `find-find-noselect'.

Please add this info to the doc strings and the Elisp manual
doc for the `find-file' family of commands.

In GNU Emacs 24.0.93.1 (i386-mingw-nt5.1.2600)
 of 2012-02-15 on MARVIN
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --no-opt --enable-checking --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include'