From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" 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: 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'" 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: 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 ) 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 ) 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 ) 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 ) 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 ) 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 ) 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" 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: 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 ) 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 ) 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" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-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: > > 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.