From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#28736: 24.5; doc of `push' Date: Sat, 7 Oct 2017 19:56:58 -0700 (PDT) Message-ID: <53afe0a4-8ce5-45fc-9e18-6bf52018c9b6@default> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1507431499 32123 195.159.176.226 (8 Oct 2017 02:58:19 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 8 Oct 2017 02:58:19 +0000 (UTC) To: 28736@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Oct 08 04:58:12 2017 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1e11n7-0006ah-Ay for geb-bug-gnu-emacs@m.gmane.org; Sun, 08 Oct 2017 04:58:09 +0200 Original-Received: from localhost ([::1]:52228 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1e11nB-0004V9-HD for geb-bug-gnu-emacs@m.gmane.org; Sat, 07 Oct 2017 22:58:13 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:48777) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1e11n3-0004V0-7S for bug-gnu-emacs@gnu.org; Sat, 07 Oct 2017 22:58:06 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1e11n0-0007KJ-5z for bug-gnu-emacs@gnu.org; Sat, 07 Oct 2017 22:58:05 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:46657) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1e11n0-0007KF-22 for bug-gnu-emacs@gnu.org; Sat, 07 Oct 2017 22:58:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1e11mz-00017l-Nx for bug-gnu-emacs@gnu.org; Sat, 07 Oct 2017 22:58:01 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 08 Oct 2017 02:58:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 28736 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.15074314414255 (code B ref -1); Sun, 08 Oct 2017 02:58:01 +0000 Original-Received: (at submit) by debbugs.gnu.org; 8 Oct 2017 02:57:21 +0000 Original-Received: from localhost ([127.0.0.1]:55338 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1e11mJ-00016U-EW for submit@debbugs.gnu.org; Sat, 07 Oct 2017 22:57:21 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:57701) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1e11mG-00016C-Js for submit@debbugs.gnu.org; Sat, 07 Oct 2017 22:57:17 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1e11mA-00072n-NE for submit@debbugs.gnu.org; Sat, 07 Oct 2017 22:57:11 -0400 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:41013) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1e11mA-00072a-KK for submit@debbugs.gnu.org; Sat, 07 Oct 2017 22:57:10 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:48671) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1e11m9-0004T1-Cm for bug-gnu-emacs@gnu.org; Sat, 07 Oct 2017 22:57:10 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1e11m6-00070A-6Q for bug-gnu-emacs@gnu.org; Sat, 07 Oct 2017 22:57:09 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:42717) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1e11m5-0006zD-U5 for bug-gnu-emacs@gnu.org; Sat, 07 Oct 2017 22:57:06 -0400 Original-Received: from aserv0021.oracle.com (aserv0021.oracle.com [141.146.126.233]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id v982v1M4032353 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Sun, 8 Oct 2017 02:57:01 GMT Original-Received: from aserv0122.oracle.com (aserv0122.oracle.com [141.146.126.236]) by aserv0021.oracle.com (8.14.4/8.14.4) with ESMTP id v982v0VH030189 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Sun, 8 Oct 2017 02:57:01 GMT Original-Received: from abhmp0006.oracle.com (abhmp0006.oracle.com [141.146.116.12]) by aserv0122.oracle.com (8.14.4/8.14.4) with ESMTP id v982uxGf015718 for ; Sun, 8 Oct 2017 02:56:59 GMT X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4588.0 (x86)] X-Source-IP: aserv0021.oracle.com [141.146.126.233] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] [fuzzy] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.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" Xref: news.gmane.org gmane.emacs.bugs:138063 Archived-At: Both the doc string and the Elisp manual entry should say that `push' returns the new value of the place that it updates. The doc says nothing about the return value. The return value is implied by the doc, which says that `push' is "morally equivalent" to (setf PLACE (cons NEWELT PLACE)), and one Can figure out that `setf' returns the new value. But the doc should just say explicitly what the return value is, instead of making users dig it out or check the code. This is morally equivalent to (setf PLACE (cons NEWELT PLACE)), except that PLACE is only evaluated once (after NEWELT). Also, the use of "morally equivalent" here, though perhaps intended to be cute, as a joke of sorts, is inappropriate and possibly confusing. What matters is that the behavior and return value are equivalent, with the proviso mentioned: that PLACE is evaluated only once (after NEWELT). In GNU Emacs 24.5.1 (i686-pc-mingw32) of 2015-04-11 on LEG570 Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --prefix=3D/c/usr --host=3Di686-pc-mingw32'