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.
> 
> I think we've been through this before.  We don't want to 
> have to commit ourselves to crap like
> 
>   (defun foo ()
>      "The return value is nil."
>      ...
>      (message "Some message we added later")
>      nil)
> 
> If the return value of a function is not documented, don't rely on
> it---doing so is a bug in your code.

Maybe you didn't notice the part about the Emacs sources doing this - and why
they do so?  

The same context in which Emacs source code might do such a thing applies to
3rd-party code.  The same reasons apply.

Or are you arguing that there are never any such reasons, and that all such
occurrences in the Emacs source code are "crap" and bugs?  If so, then please
change this bug to a code bug from a doc bug.

I don't think that the return value of these particular functions (yes,
commands) is fortuitous.  Do you?  Would you like to change the code of these
particular commands so they do not take advantage of the return value?  Even
mapping over it when a list of buffers is returned due to wildcards?

You cannot legitimately have it both ways: it is useful for Emacs source coders
but not for 3rd-party coders.  Either it is "crap" for both or useful for both.
In the former case, please correct the source code.  In the latter case, please
document the return value.