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

[Drew Adams]

> > but not for 3rd-party coders.  Either it is "crap" for both 
> > or useful for both.
> 
> It's crap.

Interesting view.  I guess the original Emacs coders were crap, then, since
*each* of the `find-file-*' commands makes a point of returning the buffer(s).
And this has been true since at least Emacs 20.

And each time the code was rewritten/updated, the maintainers again made sure to
return the buffer(s).  Not just some inadvertent mistake, this crap.

Here, for instance, is `find-file-read-only' for Emacs 20 & Emacs 24.  The other
`find-file-*' commands are all similar.

20:

(defun find-file-read-only (filename &optional wildcards)
  "Edit file FILENAME but don't allow changes.
Like \\[find-file] but marks buffer as read-only.
Use \\[toggle-read-only] to permit editing."
  (interactive "fFind file read-only: \np")
  (find-file filename wildcards)
  (toggle-read-only 1)
  (current-buffer)) ; <==== make sure we return the buffer

24:

(defun find-file-read-only (filename &optional wildcards)
  "Edit file FILENAME but don't allow changes.
Like \\[find-file], but marks buffer as read-only.
Use \\[toggle-read-only] to permit editing."
  (interactive
   (find-file-read-args "Find file read-only: "
                        (confirm-nonexistent-file-or-buffer)))
  (unless (or (and wildcards find-file-wildcards
                   (not (string-match "\\`/:" filename))
                   (string-match "[[*?]" filename))
              (file-exists-p filename))
    (error "%s does not exist" filename))
  (let ((value (find-file filename wildcards))) ; <=== use return
    (mapc (lambda (b) (with-current-buffer b (toggle-read-only 1)))
          (if (listp value) value (list value)))
    value)) ; <============ make sure we return the buffer

In the latter, the function not only takes pains to return the buffer(s).  It
also takes advantage of the fact that `find-file' does likewise.

Maybe you also think it's crap for `switch-to-buffer' & compagnie to return the
buffer, and that mention of that fact should be removed from the doc?