From mboxrd@z Thu Jan  1 00:00:00 1970
Path: news.gmane.org!not-for-mail
From: "Drew Adams" <drew.adams@oracle.com>
Newsgroups: gmane.emacs.bugs
Subject: bug#10879: 24.0.93;
	doc for `find-file' et al is missing the return value
Date: Fri, 24 Feb 2012 22:03:34 -0800
Message-ID: <ACE482DEE46E466DA018FBCC9E905152@us.oracle.com>
References: <73CE0A02B9B0423CA105B7BF7417831B@us.oracle.com>
	<87wr7by3di.fsf@gnu.org>
NNTP-Posting-Host: plane.gmane.org
Mime-Version: 1.0
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: 7bit
X-Trace: dough.gmane.org 1330149890 11635 80.91.229.3 (25 Feb 2012 06:04:50 GMT)
X-Complaints-To: usenet@dough.gmane.org
NNTP-Posting-Date: Sat, 25 Feb 2012 06:04:50 +0000 (UTC)
Cc: 10879@debbugs.gnu.org
To: "'Chong Yidong'" <cyd@gnu.org>
Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Feb 25 07:04:49 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 1S1AkO-0001W9-Bx
	for geb-bug-gnu-emacs@m.gmane.org; Sat, 25 Feb 2012 07:04:44 +0100
Original-Received: from localhost ([::1]:34482 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 1S1AkN-000108-N0
	for geb-bug-gnu-emacs@m.gmane.org; Sat, 25 Feb 2012 01:04:43 -0500
Original-Received: from eggs.gnu.org ([208.118.235.92]:39799)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1S1AkD-000103-Fc
	for bug-gnu-emacs@gnu.org; Sat, 25 Feb 2012 01:04:41 -0500
Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1S1Ak5-0002tQ-7X
	for bug-gnu-emacs@gnu.org; Sat, 25 Feb 2012 01:04:33 -0500
Original-Received: from debbugs.gnu.org ([140.186.70.43]:53083)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1S1Ak5-0002tM-3x
	for bug-gnu-emacs@gnu.org; Sat, 25 Feb 2012 01:04:25 -0500
Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1S1Amc-0003dw-7t
	for bug-gnu-emacs@gnu.org; Sat, 25 Feb 2012 01:07:02 -0500
X-Loop: help-debbugs@gnu.org
Resent-From: "Drew Adams" <drew.adams@oracle.com>
Original-Sender: debbugs-submit-bounces@debbugs.gnu.org
Resent-CC: bug-gnu-emacs@gnu.org
Resent-Date: Sat, 25 Feb 2012 06:07:02 +0000
Resent-Message-ID: <handler.10879.B10879.133014998613951@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.133014998613951
	(code B ref 10879); Sat, 25 Feb 2012 06:07:02 +0000
Original-Received: (at 10879) by debbugs.gnu.org; 25 Feb 2012 06:06:26 +0000
Original-Received: from localhost ([127.0.0.1]:54979 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.72)
	(envelope-from <debbugs-submit-bounces@debbugs.gnu.org>)
	id 1S1Am1-0003cw-Ms
	for submit@debbugs.gnu.org; Sat, 25 Feb 2012 01:06:26 -0500
Original-Received: from rcsinet15.oracle.com ([148.87.113.117]:42010)
	by debbugs.gnu.org with esmtp (Exim 4.72)
	(envelope-from <drew.adams@oracle.com>) id 1S1Aly-0003co-Op
	for 10879@debbugs.gnu.org; Sat, 25 Feb 2012 01:06:24 -0500
Original-Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238])
	by rcsinet15.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with
	ESMTP id q1P63hq8005720
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK);
	Sat, 25 Feb 2012 06:03:44 GMT
Original-Received: from acsmt358.oracle.com (acsmt358.oracle.com [141.146.40.158])
	by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id
	q1P63g6m016022
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO);
	Sat, 25 Feb 2012 06:03:42 GMT
Original-Received: from abhmt120.oracle.com (abhmt120.oracle.com [141.146.116.72])
	by acsmt358.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id
	q1P63fpg011504; Sat, 25 Feb 2012 00:03:41 -0600
Original-Received: from dradamslap1 (/10.159.40.183)
	by default (Oracle Beehive Gateway v4.0)
	with ESMTP ; Fri, 24 Feb 2012 22:03:41 -0800
X-Mailer: Microsoft Office Outlook 11
In-Reply-To: <87wr7by3di.fsf@gnu.org>
Thread-Index: AczzcSx6/w53LPBUT+2uqVV7HuNLvQAEM0FQ
X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157
X-Source-IP: acsinet22.oracle.com [141.146.126.238]
X-CT-RefId: str=0001.0A090203.4F4879C0.007E,ss=1,re=0.000,fgs=0
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:57221
Archived-At: <http://permalink.gmane.org/gmane.emacs.bugs/57221>

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