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

From: Chong Yidong <[email-masked]>
Date: Sat, 25 Feb 2012 11:54:17 +0800

"Drew Adams" <[email-masked]> writes:

> 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.