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: Sat, 25 Feb 2012 08:37:10 -0800
Message-ID: <0A371FF1256B461F9D58E0D784C4751F@us.oracle.com>
References: <73CE0A02B9B0423CA105B7BF7417831B@us.oracle.com><87wr7by3di.fsf@gnu.org><ACE482DEE46E466DA018FBCC9E905152@us.oracle.com>
	<jwvk43bmego.fsf-monnier+emacs@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 1330187926 22440 80.91.229.3 (25 Feb 2012 16:38:46 GMT)
X-Complaints-To: usenet@dough.gmane.org
NNTP-Posting-Date: Sat, 25 Feb 2012 16:38:46 +0000 (UTC)
Cc: 10879@debbugs.gnu.org, 'Chong Yidong' <cyd@gnu.org>
To: "'Stefan Monnier'" <monnier@iro.umontreal.ca>
Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Feb 25 17:38:45 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 1S1Kds-0003iL-L8
	for geb-bug-gnu-emacs@m.gmane.org; Sat, 25 Feb 2012 17:38:40 +0100
Original-Received: from localhost ([::1]:35874 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 1S1Kds-0001cR-8v
	for geb-bug-gnu-emacs@m.gmane.org; Sat, 25 Feb 2012 11:38:40 -0500
Original-Received: from eggs.gnu.org ([208.118.235.92]:36848)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1S1Kdi-0001bv-G8
	for bug-gnu-emacs@gnu.org; Sat, 25 Feb 2012 11:38:38 -0500
Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1S1Kda-0005Eb-6l
	for bug-gnu-emacs@gnu.org; Sat, 25 Feb 2012 11:38:30 -0500
Original-Received: from debbugs.gnu.org ([140.186.70.43]:54484)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1S1Kda-0005EJ-2e
	for bug-gnu-emacs@gnu.org; Sat, 25 Feb 2012 11:38:22 -0500
Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.72)
	(envelope-from <Debian-debbugs@debbugs.gnu.org>) id 1S1Kg9-0003ml-N3
	for bug-gnu-emacs@gnu.org; Sat, 25 Feb 2012 11:41:01 -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 16:41:01 +0000
Resent-Message-ID: <handler.10879.B10879.133018800814484@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.133018800814484
	(code B ref 10879); Sat, 25 Feb 2012 16:41:01 +0000
Original-Received: (at 10879) by debbugs.gnu.org; 25 Feb 2012 16:40:08 +0000
Original-Received: from localhost ([127.0.0.1]:56381 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.72)
	(envelope-from <debbugs-submit-bounces@debbugs.gnu.org>)
	id 1S1KfI-0003lZ-DO
	for submit@debbugs.gnu.org; Sat, 25 Feb 2012 11:40:08 -0500
Original-Received: from acsinet15.oracle.com ([141.146.126.227]:49085)
	by debbugs.gnu.org with esmtp (Exim 4.72)
	(envelope-from <drew.adams@oracle.com>) id 1S1KfF-0003lP-Hu
	for 10879@debbugs.gnu.org; Sat, 25 Feb 2012 11:40:06 -0500
Original-Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237])
	by acsinet15.oracle.com (Sentrion-MTA-4.2.2/Sentrion-MTA-4.2.2) with
	ESMTP id q1PGbKuQ029319
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK);
	Sat, 25 Feb 2012 16:37:23 GMT
Original-Received: from acsmt356.oracle.com (acsmt356.oracle.com [141.146.40.156])
	by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id
	q1PGbIuX029587
	(version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO);
	Sat, 25 Feb 2012 16:37:18 GMT
Original-Received: from abhmt112.oracle.com (abhmt112.oracle.com [141.146.116.64])
	by acsmt356.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id
	q1PGbIm2016314; Sat, 25 Feb 2012 10:37:18 -0600
Original-Received: from dradamslap1 (/10.159.40.183)
	by default (Oracle Beehive Gateway v4.0)
	with ESMTP ; Sat, 25 Feb 2012 08:37:17 -0800
X-Mailer: Microsoft Office Outlook 11
In-Reply-To: <jwvk43bmego.fsf-monnier+emacs@gnu.org>
Thread-Index: Aczzoqs8MXymi0RQRsCOKLWas3houAANNAVQ
X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6157
X-Source-IP: acsinet21.oracle.com [141.146.126.237]
X-Auth-Type: Internal IP
X-CT-RefId: str=0001.0A090209.4F490E44.0016,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:57239
Archived-At: <http://permalink.gmane.org/gmane.emacs.bugs/57239>

> > but not for 3rd-party coders.  Either it is "crap" for both 
> > or useful for both.
> 
> It's crap.

Interesting view.  I guess the original Emacs coders were crap, then, since
*each* of the `find-file-*' commands makes a point of returning the buffer(s).
And this has been true since at least Emacs 20.

And each time the code was rewritten/updated, the maintainers again made sure to
return the buffer(s).  Not just some inadvertent mistake, this crap.

Here, for instance, is `find-file-read-only' for Emacs 20 & Emacs 24.  The other
`find-file-*' commands are all similar.

20:

(defun find-file-read-only (filename &optional wildcards)
  "Edit file FILENAME but don't allow changes.
Like \\[find-file] but marks buffer as read-only.
Use \\[toggle-read-only] to permit editing."
  (interactive "fFind file read-only: \np")
  (find-file filename wildcards)
  (toggle-read-only 1)
  (current-buffer)) ; <==== make sure we return the buffer

24:

(defun find-file-read-only (filename &optional wildcards)
  "Edit file FILENAME but don't allow changes.
Like \\[find-file], but marks buffer as read-only.
Use \\[toggle-read-only] to permit editing."
  (interactive
   (find-file-read-args "Find file read-only: "
                        (confirm-nonexistent-file-or-buffer)))
  (unless (or (and wildcards find-file-wildcards
		   (not (string-match "\\`/:" filename))
		   (string-match "[[*?]" filename))
	      (file-exists-p filename))
    (error "%s does not exist" filename))
  (let ((value (find-file filename wildcards))) ; <=== use return
    (mapc (lambda (b) (with-current-buffer b (toggle-read-only 1)))
	  (if (listp value) value (list value)))
    value)) ; <============ make sure we return the buffer

In the latter, the function not only takes pains to return the buffer(s).  It
also takes advantage of the fact that `find-file' does likewise.

Maybe you also think it's crap for `switch-to-buffer' & compagnie to return the
buffer, and that mention of that fact should be removed from the doc?