From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.org!not-for-mail
From: Chong Yidong <cyd@gnu.org>
Newsgroups: gmane.emacs.bugs
Subject: bug#10879: 24.0.93;
	doc for `find-file' et al is missing the return value
Date: Sat, 25 Feb 2012 11:54:17 +0800
Message-ID: <87wr7by3di.fsf@gnu.org>
References: <73CE0A02B9B0423CA105B7BF7417831B@us.oracle.com>
NNTP-Posting-Host: plane.gmane.org
Mime-Version: 1.0
Content-Type: text/plain
X-Trace: dough.gmane.org 1330142133 5100 80.91.229.3 (25 Feb 2012 03:55:33 GMT)
X-Complaints-To: usenet@dough.gmane.org
NNTP-Posting-Date: Sat, 25 Feb 2012 03:55:33 +0000 (UTC)
Cc: 10879@debbugs.gnu.org
To: "Drew Adams" <drew.adams@oracle.com>
Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Feb 25 04:55:32 2012
Return-path: <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org>
Envelope-to: geb-bug-gnu-emacs@m.gmane.org
Original-Received: from lists.gnu.org ([140.186.70.17])
	by plane.gmane.org with esmtp (Exim 4.69)
	(envelope-from <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org>)
	id 1S18jJ-0003lX-P1
	for geb-bug-gnu-emacs@m.gmane.org; Sat, 25 Feb 2012 04:55:29 +0100
Original-Received: from localhost ([::1]:45815 helo=lists.gnu.org)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org>)
	id 1S18jJ-00014F-EW
	for geb-bug-gnu-emacs@m.gmane.org; Fri, 24 Feb 2012 22:55:29 -0500
Original-Received: from eggs.gnu.org ([208.118.235.92]:60656)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1S18jG-00013z-EP
	for bug-gnu-emacs@gnu.org; Fri, 24 Feb 2012 22:55:27 -0500
Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1S18jF-0003WU-7e
	for bug-gnu-emacs@gnu.org; Fri, 24 Feb 2012 22:55:26 -0500
Original-Received: from debbugs.gnu.org ([140.186.70.43]:52983)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1S18jF-0003WQ-3t
	for bug-gnu-emacs@gnu.org; Fri, 24 Feb 2012 22:55:25 -0500
Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1S18ll-0006lw-QW
	for bug-gnu-emacs@gnu.org; Fri, 24 Feb 2012 22:58:01 -0500
X-Loop: help-debbugs@gnu.org
Resent-From: Chong Yidong <cyd@gnu.org>
Original-Sender: debbugs-submit-bounces@debbugs.gnu.org
Resent-CC: bug-gnu-emacs@gnu.org
Resent-Date: Sat, 25 Feb 2012 03:58:01 +0000
Resent-Message-ID: <handler.10879.B10879.133014222525968@debbugs.gnu.org>
Resent-Sender: help-debbugs@gnu.org
X-GNU-PR-Message: followup 10879
X-GNU-PR-Package: emacs
X-GNU-PR-Keywords: 
Original-Received: via spool by 10879-submit@debbugs.gnu.org id=B10879.133014222525968
	(code B ref 10879); Sat, 25 Feb 2012 03:58:01 +0000
Original-Received: (at 10879) by debbugs.gnu.org; 25 Feb 2012 03:57:05 +0000
Original-Received: from localhost ([127.0.0.1]:54880 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.72)
	(envelope-from <debbugs-submit-bounces@debbugs.gnu.org>)
	id 1S18kq-0006km-TD
	for submit@debbugs.gnu.org; Fri, 24 Feb 2012 22:57:05 -0500
Original-Received: from fencepost.gnu.org ([140.186.70.10]:52757)
	by debbugs.gnu.org with esmtp (Exim 4.72)
	(envelope-from <cyd@gnu.org>) id 1S18ko-0006kf-M8
	for 10879@debbugs.gnu.org; Fri, 24 Feb 2012 22:57:03 -0500
Original-Received: from bb116-14-103-36.singnet.com.sg ([116.14.103.36]:55275
	helo=furball)
	by fencepost.gnu.org with esmtpsa (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16)
	(Exim 4.71) (envelope-from <cyd@gnu.org>)
	id 1S18iG-0007CD-Ql; Fri, 24 Feb 2012 22:54:25 -0500
In-Reply-To: <73CE0A02B9B0423CA105B7BF7417831B@us.oracle.com> (Drew Adams's
	message of "Fri, 24 Feb 2012 09:07:28 -0800")
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.0.93 (gnu/linux)
X-BeenThere: debbugs-submit@debbugs.gnu.org
X-Mailman-Version: 2.1.13
Precedence: list
X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2)
X-Received-From: 140.186.70.43
X-BeenThere: bug-gnu-emacs@gnu.org
List-Id: "Bug reports for GNU Emacs,
	the Swiss army knife of text editors" <bug-gnu-emacs.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/bug-gnu-emacs>,
	<mailto:bug-gnu-emacs-request@gnu.org?subject=unsubscribe>
List-Archive: <http://lists.gnu.org/archive/html/bug-gnu-emacs>
List-Post: <mailto:bug-gnu-emacs@gnu.org>
List-Help: <mailto:bug-gnu-emacs-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/bug-gnu-emacs>,
	<mailto:bug-gnu-emacs-request@gnu.org?subject=subscribe>
Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org
Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org
Xref: news.gmane.org gmane.emacs.bugs:57207
Archived-At: <http://permalink.gmane.org/gmane.emacs.bugs/57207>

"Drew Adams" <drew.adams@oracle.com> 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.