From unknown Sun Jun 22 08:02:21 2025 X-Loop: help-debbugs@gnu.org Subject: bug#15116: 24.3.50; doc of `set-match-data' Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 17 Aug 2013 15:28:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 15116 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 15116@debbugs.gnu.org X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Received: via spool by submit@debbugs.gnu.org id=B.137675323114237 (code B ref -1); Sat, 17 Aug 2013 15:28:02 +0000 Received: (at submit) by debbugs.gnu.org; 17 Aug 2013 15:27:11 +0000 Received: from localhost ([127.0.0.1]:36893 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VAiPH-0003hZ-0E for submit@debbugs.gnu.org; Sat, 17 Aug 2013 11:27:11 -0400 Received: from eggs.gnu.org ([208.118.235.92]:41763) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VAiPE-0003hM-2G for submit@debbugs.gnu.org; Sat, 17 Aug 2013 11:27:08 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VAiOx-0005Mw-PV for submit@debbugs.gnu.org; Sat, 17 Aug 2013 11:27:02 -0400 X-Spam-Checker-Version: SpamAssassin 3.3.2 (2011-06-06) on eggs.gnu.org X-Spam-Level: X-Spam-Status: No, score=-101.9 required=5.0 tests=BAYES_00, USER_IN_WHITELIST autolearn=disabled version=3.3.2 Received: from lists.gnu.org ([2001:4830:134:3::11]:56658) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VAiOx-0005Ml-MI for submit@debbugs.gnu.org; Sat, 17 Aug 2013 11:26:51 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:43422) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VAiOo-0002du-Uy for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 11:26:51 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VAiOg-0005Jp-Cf for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 11:26:42 -0400 Received: from userp1040.oracle.com ([156.151.31.81]:39297) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VAiOg-0005Jc-5o for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 11:26:34 -0400 Received: from ucsinet21.oracle.com (ucsinet21.oracle.com [156.151.31.93]) by userp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r7HFQWqH017180 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK) for ; Sat, 17 Aug 2013 15:26:33 GMT Received: from userz7021.oracle.com (userz7021.oracle.com [156.151.31.85]) by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r7HFQVwD021693 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Sat, 17 Aug 2013 15:26:32 GMT Received: from abhmt111.oracle.com (abhmt111.oracle.com [141.146.116.63]) by userz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r7HFQVUm021690 for ; Sat, 17 Aug 2013 15:26:31 GMT MIME-Version: 1.0 Message-ID: Date: Sat, 17 Aug 2013 08:26:30 -0700 (PDT) From: Drew Adams X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6680.5000 (x86)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Source-IP: ucsinet21.oracle.com [156.151.31.93] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.4.x-2.6.x [generic] X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2001:4830:134:3::11 X-Spam-Score: -2.4 (--) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -2.4 (--) Both the doc string and (elisp) Entire Match Data should say what the return value is. The doc for every Emacs function should say what the return value is. In GNU Emacs 24.3.50.1 (i686-pc-mingw32) of 2013-08-07 on ODIEONE Bzr revision: 113750 lekktu@gmail.com-20130808011911-0jzpc9xuncegg6x9 Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --prefix=3D/c/Devel/emacs/binary --enable-checking=3Dyes,glyphs CFLAGS=3D-O0 -g3 LDFLAGS=3D-Lc:/Devel/emacs/lib CPPFLAGS=3D-Ic:/Devel/emacs/include' From unknown Sun Jun 22 08:02:21 2025 X-Loop: help-debbugs@gnu.org Subject: bug#15116: 24.3.50; doc of `set-match-data' Resent-From: Juanma Barranquero Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 17 Aug 2013 15:42:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 15116 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Drew Adams Cc: 15116@debbugs.gnu.org Received: via spool by 15116-submit@debbugs.gnu.org id=B15116.137675407715824 (code B ref 15116); Sat, 17 Aug 2013 15:42:02 +0000 Received: (at 15116) by debbugs.gnu.org; 17 Aug 2013 15:41:17 +0000 Received: from localhost ([127.0.0.1]:36919 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VAicv-00047A-DL for submit@debbugs.gnu.org; Sat, 17 Aug 2013 11:41:17 -0400 Received: from mail-ea0-f175.google.com ([209.85.215.175]:60534) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VAicq-00046s-5I for 15116@debbugs.gnu.org; Sat, 17 Aug 2013 11:41:14 -0400 Received: by mail-ea0-f175.google.com with SMTP id m14so1497650eaj.20 for <15116@debbugs.gnu.org>; Sat, 17 Aug 2013 08:41:06 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc:content-type; bh=sw2uGdbc7JN2uza2zhvo6I2fsYWSbwsrdL/FH9VZI9Y=; b=IqJhXMXyzUHVR12YeuO6TViXgv4TkzPvjRjs+jY6BkLQDLjfF50GMQsCsSyG6UGK9f w3j4NV7TRhRAVCPfYQad45igXBuN2TV/enJe8nwjAJ4vtla/hZqvmnVSnqR5svDwftao DKDFaf9NOyZCVRwv03x85mNcb5Jhh0wsX1/sGW4JZyhcn45PmPKywyViFo1DQU1uGApu d+F61rKbXQ3b3yKu1h/Sb0EBH/hoMu01AUb4hp5LELvdjN3AkKZJ29ZbH+xSiYJOqMCo V2A/BDQKa1cZfiVvlNzYMB3OdfD/ECnHAhpLzzwdiIu3IIT/WjtS3BPTpturOTqKIBVm KUFw== X-Received: by 10.14.174.195 with SMTP id x43mr4650883eel.47.1376754066382; Sat, 17 Aug 2013 08:41:06 -0700 (PDT) MIME-Version: 1.0 Received: by 10.14.133.15 with HTTP; Sat, 17 Aug 2013 08:40:26 -0700 (PDT) In-Reply-To: References: From: Juanma Barranquero Date: Sat, 17 Aug 2013 17:40:26 +0200 Message-ID: Content-Type: text/plain; charset=UTF-8 X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.7 (/) On Sat, Aug 17, 2013 at 5:26 PM, Drew Adams wrote: > The doc for every Emacs function should say what the return value is. Hm. I disagree. Many functions are used just by their side effects, and forcing them to declare a return value and keep it forever back-compatible is unreasonable, especially when the return value is quite arbitrary. You simply shouldn't rely on them returning anything sensible. J From unknown Sun Jun 22 08:02:21 2025 X-Loop: help-debbugs@gnu.org Subject: bug#15116: 24.3.50; doc of `set-match-data' Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 17 Aug 2013 16:16:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 15116 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: Juanma Barranquero Cc: 15116@debbugs.gnu.org Received: via spool by 15116-submit@debbugs.gnu.org id=B15116.137675610219321 (code B ref 15116); Sat, 17 Aug 2013 16:16:01 +0000 Received: (at 15116) by debbugs.gnu.org; 17 Aug 2013 16:15:02 +0000 Received: from localhost ([127.0.0.1]:36950 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VAj9Y-00051J-K0 for submit@debbugs.gnu.org; Sat, 17 Aug 2013 12:15:01 -0400 Received: from aserp1040.oracle.com ([141.146.126.69]:48359) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VAj9W-000510-4o for 15116@debbugs.gnu.org; Sat, 17 Aug 2013 12:14:58 -0400 Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by aserp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r7HGEpvs016449 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sat, 17 Aug 2013 16:14:52 GMT Received: from aserz7022.oracle.com (aserz7022.oracle.com [141.146.126.231]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r7HGEpbH027290 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sat, 17 Aug 2013 16:14:51 GMT Received: from abhmt111.oracle.com (abhmt111.oracle.com [141.146.116.63]) by aserz7022.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r7HGEpHx027287; Sat, 17 Aug 2013 16:14:51 GMT MIME-Version: 1.0 Message-ID: <1e335257-878b-4e7a-88d2-be252422b045@default> Date: Sat, 17 Aug 2013 09:14:50 -0700 (PDT) From: Drew Adams References: In-Reply-To: X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6680.5000 (x86)] Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-Spam-Score: -5.0 (-----) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) > > The doc for every Emacs function should say what the return value is. >=20 > Hm. I disagree. Many functions are used just by their side effects, 1. "Many" in absolute terms. Very few in relative terms. They are exceptions to the rule, not the norm. This is Lisp, not C. 2. Such exceptional functions should be *explicitly documented* as such. See below. See the Common Lisp spec and doc, as a good model to follow. > and forcing them to declare a return value and keep it forever > back-compatible is unreasonable, especially when the return value is > quite arbitrary. You simply shouldn't rely on them returning anything > sensible. 100% agreed, wrt those few, exceptional functions, *provided* that this exceptional do-not-rely-on-return-value behavior is explicitly documented. Users get what they deserve, *provided* they have been told explicitly not to count on the return value. If we do not tell them that then they deserve better. They deserve and should expect a reasonable return value if we do not advise them otherwise. The (unwritten) rule should *not* be that if the Emacs doc says nothing about a return value then you should assume that it is undefined (you cannot rely on it). The rule should be that the doc for each function either (a) specifies the return value or (b) tells you that the return value is undefined (do not rely on it) and the function is used only for its side effects. In sum: the rule should be explicitness in our doc, not just lazy omission of such important information. FWIW, I was more exact in what I said in bug #15117: If, for some special (good) reason, code should not rely on the=20 return value of some function then this fact should be stated=20 explicitly in the doc: "This function is used only for its side=20 effects; the return value is undefined." This is Lisp, not C -=20 return values are the norm, not the exception. NB. "for some *special* (*good*) reason". From unknown Sun Jun 22 08:02:21 2025 X-Loop: help-debbugs@gnu.org Subject: bug#15116: 24.3.50; doc of `set-match-data' Resent-From: Glenn Morris Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 17 Aug 2013 17:33:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 15116 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: To: 15116@debbugs.gnu.org Received: via spool by 15116-submit@debbugs.gnu.org id=B15116.137676076431745 (code B ref 15116); Sat, 17 Aug 2013 17:33:01 +0000 Received: (at 15116) by debbugs.gnu.org; 17 Aug 2013 17:32:44 +0000 Received: from localhost ([127.0.0.1]:37107 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VAkMm-0008Fx-Gc for submit@debbugs.gnu.org; Sat, 17 Aug 2013 13:32:44 -0400 Received: from fencepost.gnu.org ([208.118.235.10]:33109 ident=Debian-exim) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VAkMl-0008Fo-CR for 15116@debbugs.gnu.org; Sat, 17 Aug 2013 13:32:43 -0400 Received: from rgm by fencepost.gnu.org with local (Exim 4.71) (envelope-from ) id 1VAkMj-0005yB-CC; Sat, 17 Aug 2013 13:32:41 -0400 From: Glenn Morris References: X-Spook: dictionary Telex STARLAN bemd Cocaine AFSPC kibo Aladdin X-Ran: Q,^b802xbb{~4,41BTX=Ns@W.i[`x(LqTn^|Xm]{_tQ,BWK[q-V]z)pElkoh+~jU'.ll7A X-Hue: blue X-Attribution: GM Date: Sat, 17 Aug 2013 13:32:41 -0400 In-Reply-To: (Drew Adams's message of "Sat, 17 Aug 2013 08:26:30 -0700 (PDT)") Message-ID: User-Agent: Gnus (www.gnus.org), GNU Emacs (www.gnu.org/software/emacs/) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Spam-Score: -7.7 (-------) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -7.7 (-------) Drew Adams wrote: > The doc for every Emacs function should say what the return value is. Awesome, so now we can expect 100s of reports about this, complete with little lectures when we disagree. As Juanma said; no, they shouldn't. From debbugs-submit-bounces@debbugs.gnu.org Sat Aug 17 13:39:13 2013 Received: (at control) by debbugs.gnu.org; 17 Aug 2013 17:39:13 +0000 Received: from localhost ([127.0.0.1]:37118 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VAkT2-0008Rk-HH for submit@debbugs.gnu.org; Sat, 17 Aug 2013 13:39:12 -0400 Received: from fencepost.gnu.org ([208.118.235.10]:33181 ident=Debian-exim) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VAkT0-0008Rc-Fy for control@debbugs.gnu.org; Sat, 17 Aug 2013 13:39:10 -0400 Received: from rgm by fencepost.gnu.org with local (Exim 4.71) (envelope-from ) id 1VAkT0-0006af-0A for control@debbugs.gnu.org; Sat, 17 Aug 2013 13:39:10 -0400 Date: Sat, 17 Aug 2013 13:39:10 -0400 Message-Id: Subject: control message for bug 15116 To: X-Mailer: mail (GNU Mailutils 2.1) From: Glenn Morris X-Spam-Score: -7.7 (-------) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -7.7 (-------) tag 15116 wontfix From unknown Sun Jun 22 08:02:21 2025 X-Loop: help-debbugs@gnu.org Subject: bug#15116: 24.3.50; doc of `set-match-data' Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 17 Aug 2013 17:43:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 15116 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: wontfix To: Glenn Morris , 15116@debbugs.gnu.org Received: via spool by 15116-submit@debbugs.gnu.org id=B15116.1376761376433 (code B ref 15116); Sat, 17 Aug 2013 17:43:02 +0000 Received: (at 15116) by debbugs.gnu.org; 17 Aug 2013 17:42:56 +0000 Received: from localhost ([127.0.0.1]:37122 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VAkWd-00006u-FI for submit@debbugs.gnu.org; Sat, 17 Aug 2013 13:42:55 -0400 Received: from aserp1040.oracle.com ([141.146.126.69]:19465) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VAkWb-00006W-Gd for 15116@debbugs.gnu.org; Sat, 17 Aug 2013 13:42:53 -0400 Received: from ucsinet21.oracle.com (ucsinet21.oracle.com [156.151.31.93]) by aserp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r7HHgkCn021985 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sat, 17 Aug 2013 17:42:47 GMT Received: from aserz7021.oracle.com (aserz7021.oracle.com [141.146.126.230]) by ucsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r7HHgjTA016595 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sat, 17 Aug 2013 17:42:46 GMT Received: from abhmt111.oracle.com (abhmt111.oracle.com [141.146.116.63]) by aserz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r7HHgjwn015324; Sat, 17 Aug 2013 17:42:45 GMT MIME-Version: 1.0 Message-ID: Date: Sat, 17 Aug 2013 10:42:44 -0700 (PDT) From: Drew Adams References: In-Reply-To: X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6680.5000 (x86)] Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Source-IP: ucsinet21.oracle.com [156.151.31.93] X-Spam-Score: -5.0 (-----) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) > Awesome, so now we can expect 100s of reports about this, complete > with little lectures when we disagree. Too bad. It's not about minimizing development. It's about helping users and specifying clearly (yes, for developers too) just what the language is. If Common Lisp can do it (and has done it for 30 years) then the self-vaunted "self-documenting" editor can do it too. It just means thinking also `user' and `spec', not just `code'. Emacs is a big boy now; he should be able to handle this. From unknown Sun Jun 22 08:02:21 2025 X-Loop: help-debbugs@gnu.org Subject: bug#15116: 24.3.50; doc of `set-match-data' Resent-From: Juanma Barranquero Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 17 Aug 2013 17:46:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 15116 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: wontfix To: Drew Adams Cc: 15116@debbugs.gnu.org Received: via spool by 15116-submit@debbugs.gnu.org id=B15116.13767615303117 (code B ref 15116); Sat, 17 Aug 2013 17:46:02 +0000 Received: (at 15116) by debbugs.gnu.org; 17 Aug 2013 17:45:30 +0000 Received: from localhost ([127.0.0.1]:37126 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VAkZ8-0000na-Ba for submit@debbugs.gnu.org; Sat, 17 Aug 2013 13:45:30 -0400 Received: from mail-ea0-f179.google.com ([209.85.215.179]:33319) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VAkZ5-0000cL-Mb for 15116@debbugs.gnu.org; Sat, 17 Aug 2013 13:45:28 -0400 Received: by mail-ea0-f179.google.com with SMTP id b10so1560765eae.10 for <15116@debbugs.gnu.org>; Sat, 17 Aug 2013 10:45:21 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc:content-type; bh=0DpcZlQ8N0D+hpHSHeQyRen8BkdJ+9hJOaSn4qF9Brw=; b=H87biWBSanC3T9o4xYkDveJ3hxwpq+DbZj35kiKwgnI+PLPJVqMn3zc1dG3unifyYY uBgycNmGHJ9qwZmHvFkCF12uSRuUZn2IAyEcbJHHuEoU7PQFpT1HSV9QHwIt9ZJe1dgx 22em2UyTkzmJHssyrW5RVgSTCQxrfoLG69dcKCJfkR4P4vXB/E0yIDMegOZBlqe9t90n za9zkOuD5Eu/BoD5DRZq76lylXzUyZK2Z2Y6ZMgNfRmPGCYWk4OJKRubgpmqD8ECRszg oOR9XjVjtmok5phP8du4hsHEPvDPG8EnSRItsTtWUvoe1nAH1/ykgFpOoKONJDMhukl/ lXvw== X-Received: by 10.14.113.137 with SMTP id a9mr7239998eeh.3.1376761521606; Sat, 17 Aug 2013 10:45:21 -0700 (PDT) MIME-Version: 1.0 Received: by 10.14.133.15 with HTTP; Sat, 17 Aug 2013 10:44:41 -0700 (PDT) In-Reply-To: <1e335257-878b-4e7a-88d2-be252422b045@default> References: <1e335257-878b-4e7a-88d2-be252422b045@default> From: Juanma Barranquero Date: Sat, 17 Aug 2013 19:44:41 +0200 Message-ID: Content-Type: text/plain; charset=UTF-8 X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.7 (/) On Sat, Aug 17, 2013 at 6:14 PM, Drew Adams wrote: > The (unwritten) rule should *not* be that if the Emacs doc says nothing > about a return value then you should assume that it is undefined (you > cannot rely on it). > > The rule should be that the doc for each function either (a) specifies > the return value or (b) tells you that the return value is undefined > (do not rely on it) and the function is used only for its side effects. > > In sum: the rule should be explicitness in our doc, not just lazy > omission of such important information. Sorry, I still disagree. The general rule is always that if nothing is said, nothing can be assumed (or, alternatively, assume at your own peril). Many functions *do* declare their return value, but that is generally because the return value is potentially useful. More power to them (and us). For the rest, adding a note saying that the return value is undefined is nice, but in many cases unnecessary and verbose IMO. And I don't think laziness is involved, BTW. > If, for some special (good) reason, code should not rely on the > return value of some function then this fact should be stated > explicitly in the doc: I don't see how the coder could fail to notice that there's a good reason not to use the return value of some specific function, if that return value is undocumented. This is not theoretical. Sometimes I've used the return value of a function without looking at its docstring. When afterwards I've wondered whether I was doing the right thing, a simple look and the realization that it wasn't, in fact, documented, was enough to go "oh, bummer" and fix my code. "The return value of this function is undefined" would've added nothing of value, except in functions with very large or complex docstrings. And, in this cases, the docstring author *can* add the notice; it's not forbidden. Summarizing: I agree it can be OK to add the notice. I don't agree there's some kind of obligation to document that it is undefined. J From unknown Sun Jun 22 08:02:21 2025 X-Loop: help-debbugs@gnu.org Subject: bug#15116: 24.3.50; doc of `set-match-data' Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 17 Aug 2013 18:38:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 15116 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: wontfix To: Juanma Barranquero Cc: 15116@debbugs.gnu.org Received: via spool by 15116-submit@debbugs.gnu.org id=B15116.137676465510238 (code B ref 15116); Sat, 17 Aug 2013 18:38:02 +0000 Received: (at 15116) by debbugs.gnu.org; 17 Aug 2013 18:37:35 +0000 Received: from localhost ([127.0.0.1]:37175 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VAlNV-0002f2-K2 for submit@debbugs.gnu.org; Sat, 17 Aug 2013 14:37:34 -0400 Received: from userp1040.oracle.com ([156.151.31.81]:40623) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VAlNT-0002em-01 for 15116@debbugs.gnu.org; Sat, 17 Aug 2013 14:37:32 -0400 Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by userp1040.oracle.com (Sentrion-MTA-4.3.1/Sentrion-MTA-4.3.1) with ESMTP id r7HIbNpP010861 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sat, 17 Aug 2013 18:37:24 GMT Received: from userz7021.oracle.com (userz7021.oracle.com [156.151.31.85]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r7HIbMjn017524 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sat, 17 Aug 2013 18:37:22 GMT Received: from abhmt111.oracle.com (abhmt111.oracle.com [141.146.116.63]) by userz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id r7HIbLbP001160; Sat, 17 Aug 2013 18:37:21 GMT MIME-Version: 1.0 Message-ID: Date: Sat, 17 Aug 2013 11:37:20 -0700 (PDT) From: Drew Adams References: <1e335257-878b-4e7a-88d2-be252422b045@default> In-Reply-To: X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6680.5000 (x86)] Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-Spam-Score: -5.0 (-----) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -5.0 (-----) > > The (unwritten) rule should *not* be that if the Emacs doc says nothing > > about a return value then you should assume that it is undefined (you > > cannot rely on it). > > > > The rule should be that the doc for each function either (a) specifies > > the return value or (b) tells you that the return value is undefined > > (do not rely on it) and the function is used only for its side effects. > > > > In sum: the rule should be explicitness in our doc, not just lazy > > omission of such important information. >=20 > Sorry, I still disagree. The general rule is always that if nothing is > said, nothing can be assumed (or, alternatively, assume at your own > peril). A user's OWN rule has to be, yes, that if the doc says nothing then all bets are off. That is more or less of the same value as "caveat emptor" and "Don't talk to strangers": advice that says that you cannot depend on kindness or honesty etc. But that is not an excuse for the doc to help users less than it can. Just because a user has to be careful and not assume anything about what is not said explicitly is not a reason to dispense with helping users. It is not a reason to not be explicit. The wise user even applies the same rule to what IS said. It might just be incorrect, so don't trust it completely. That is not an excuse for the doc to be wrong, is it? You are confusing, I think, what a user can assume with what we should tell users, to help them use the product. We should not be thinking only like litigation defense lawyers here ("We never promised you..."). We should be thinking of users and how best to help them. They are, after all, the raison d'etre du produit. You seem to want to put the burden on users, not Emacs. That's backwards. Forget about what users can rightfully assume or claim, or what they might complain about. Think about what helps them. > Many functions *do* declare their return value, but that is > generally because the return value is potentially useful. More power > to them (and us). For the rest, adding a note saying that the return > value is undefined is nice, but in many cases unnecessary and verbose > IMO. And I don't think laziness is involved, BTW. The burden should be on the doc, not the user. If the language designers intend for a particular function to be used only for side effects then we can and should help users by letting them know that that is the case. How much effort does that take? How verbose does it make the doc to add that for the few functions to which it applies? Anything less than that is discourteous, unless it is an oversight. And that is the case whether the reason is laziness or something else. > > If, for some special (good) reason, code should not rely on the > > return value of some function then this fact should be stated > > explicitly in the doc: >=20 > I don't see how the coder could fail to notice that there's a good > reason not to use the return value of some specific function, if that > return value is undocumented. You don't see how someone can fail to notice the reason a function is to be used only for side effects? Notice the reason? Think again. Do you take the same attitude wrt functions that modify list structure? Scheme even goes to the trouble of giving them names that end in `!', to make explicit (even obvious!) that they are "destructive". Would you take the point of view that their doc need say nothing about this part of their behavior, under the rationale that (a) users should not fail to figure this out on their own, and (b) users should not assume these functions are non-destructive (or destructive), since the doc says nothing about this. Why not just remove the doc altogether? That way we promise nothing, the user is careful and figures things out alone, we save lots of development effort, and verbosity goes to zero! Hurrah. > This is not theoretical. Sometimes I've used the return value of a > function without looking at its docstring. When afterwards I've > wondered whether I was doing the right thing, a simple look and the > realization that it wasn't, in fact, documented, was enough to go "oh, > bummer" and fix my code. "The return value of this function is > undefined" would've added nothing of value, except in functions with > very large or complex docstrings. And, in this cases, the docstring > author *can* add the notice; it's not forbidden. >=20 > Summarizing: I agree it can be OK to add the notice. I don't agree > there's some kind of obligation to document that it is undefined. If it can be OK in your opinion, then we can make the effort to help users by adding it. It's about doing the right thing. Does that mean "obligation" to you? Just because something is not obligatory and enforced somehow, that does not mean that it should not be done. Whether you call it "obligation" or not, we can, and so we should, help users by being explicit about what side effects occur and what value is returned. There is really no reason not to share this info with those for whom the product is developed. It just helps. Emacs should take a tip from its big brother, Common Lisp: write it down, for all to see. (You might be surprised how much that will help even Emacs developers.) From unknown Sun Jun 22 08:02:21 2025 X-Loop: help-debbugs@gnu.org Subject: bug#15116: 24.3.50; doc of `set-match-data' Resent-From: Juanma Barranquero Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 18 Aug 2013 02:08:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 15116 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: wontfix To: Drew Adams Cc: 15116@debbugs.gnu.org Received: via spool by 15116-submit@debbugs.gnu.org id=B15116.137679164629007 (code B ref 15116); Sun, 18 Aug 2013 02:08:01 +0000 Received: (at 15116) by debbugs.gnu.org; 18 Aug 2013 02:07:26 +0000 Received: from localhost ([127.0.0.1]:37641 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VAsOr-0007Xm-Hx for submit@debbugs.gnu.org; Sat, 17 Aug 2013 22:07:26 -0400 Received: from mail-ea0-f176.google.com ([209.85.215.176]:38317) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1VAsOo-0007XZ-VZ for 15116@debbugs.gnu.org; Sat, 17 Aug 2013 22:07:23 -0400 Received: by mail-ea0-f176.google.com with SMTP id q16so1659577ead.35 for <15116@debbugs.gnu.org>; Sat, 17 Aug 2013 19:07:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:from:date:message-id:subject:to :cc:content-type; bh=N7r8L06bNb9fFGf7IO8VjLKZlhmSdmgfMHRAJsa6q/o=; b=QjSTp9IZrQDKScBdc9Naj7LgPzW6QEgwpGShmej+lHLvFJvl7PPN4Os18l2StsUc5d rM5acMN/YwcvTY93qaSvJW/qs4q470z80YimGNxgco11gwrp7dl08Zlayi45z38N8lOr BN9HimAJdYA3/TZ/XWaDhm32azWFaZPwykBvAyw0/WZezhn3R8MgEEpjPPRZD5qjbJLh 3dJfHMLp+k5yTkLyR5nUSwcSmp/aFEBuoYJsrN8+Aey57UcQh8bmFCCDJmm6eAMf8OyN d2N5ERGQ3cGuLu3zgW3Fm2G+Y20kVQ4EhBp8sIycM+e7Nxg7pZuI3a734YLXzzvkIr0S 6TlA== X-Received: by 10.14.209.133 with SMTP id s5mr37089eeo.49.1376791636718; Sat, 17 Aug 2013 19:07:16 -0700 (PDT) MIME-Version: 1.0 Received: by 10.14.133.15 with HTTP; Sat, 17 Aug 2013 19:06:36 -0700 (PDT) In-Reply-To: References: <1e335257-878b-4e7a-88d2-be252422b045@default> From: Juanma Barranquero Date: Sun, 18 Aug 2013 04:06:36 +0200 Message-ID: Content-Type: text/plain; charset=UTF-8 X-Spam-Score: -0.7 (/) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: -0.7 (/) On Sat, Aug 17, 2013 at 8:37 PM, Drew Adams wrote: > But that is not an excuse for the doc to help users less than it can. > Just because a user has to be careful and not assume anything about > what is not said explicitly is not a reason to dispense with helping > users. It is not a reason to not be explicit. Sorry, I again disagree. I don't think that not documenting a return value, when there's is a clear default ("if not documented, nothing can be assumed") is being unhelpful. For every documentation there are things that must be clearly stated, and others that can be left unsaid because they are part of the landscape. Someone who pretends to use an Emacs function already has in their mental landscape the idea that: not documented, nothing can be assumed. > The wise user even applies the same rule to what IS said. It might > just be incorrect, so don't trust it completely. That is not an > excuse for the doc to be wrong, is it? Not stating every repetitive nuance is not "being wrong". > You are confusing, I think, what a user can assume with what we should > tell users, to help them use the product. No, I don't think so. > We should not be thinking only like litigation defense lawyers here > ("We never promised you..."). That's a straw man. No one here is thinking that. > We should be thinking of users and how > best to help them. They are, after all, the raison d'etre du produit. Well, yes, but no all of us define "help them" in the same way that you do. > You seem to want to put the burden on users, not Emacs. That's > backwards. Forget about what users can rightfully assume or claim, > or what they might complain about. Think about what helps them. Again, please don't put words in my mouth that I didn't say, or ideas in my words that I didn't express and don't really believe. No one is talking about "what the user can rightfully [...] claim". > The burden should be on the doc, not the user. If the language > designers intend for a particular function to be used only for side > effects then we can and should help users by letting them know that > that is the case. How much effort does that take? How verbose does > it make the doc to add that for the few functions to which it applies? How difficult is for the user to understand that, not mentioned => do not assume anything? Should we state in *every* docstring *every* assumption that can be possibly misinterpreted, however common and clear it is? At which point do we stop and just trust the user to be smart? > Anything less than that is discourteous, unless it is an oversight. > And that is the case whether the reason is laziness or something else. That's not an argument, that's just *your* opinion. > You don't see how someone can fail to notice the reason a function > is to be used only for side effects? Notice the reason? Think again. Nothing to "think again". Yes, I don't see how the coder can fail to notice that the function's return is undocumented and so there's a good reason not to use its return value. We can dance all night and still nothing will change. > Do you take the same attitude wrt functions that modify list structure? > Scheme even goes to the trouble of giving them names that end in `!', > to make explicit (even obvious!) that they are "destructive". Nonsense. That I defend not having to document a *non-useful* return value does not imply that I defend *not saying* in the docstring that the function is called for side effects only, or not clearly explaining what the function *does*. Returning a value, it *doesn't* do, in any meaningful way. Let's concentrate in documenting what the function does, because what it doesn't do... that could be very long indeed. > (b) users should not > assume these functions are non-destructive (or destructive), since the > doc says nothing about this. Your connection between "not documenting its return value" and "not explaining that they have side effects (destructive or not)" is spurious and I don't accept it. > Why not just remove the doc altogether? That way we promise nothing, > the user is careful and figures things out alone, we save lots of > development effort, and verbosity goes to zero! Hurrah. I'd like you ask you to please skip all that "promise" rhetoric. It's false, it's insulting, and does not help in this discussion. (Also, as you know very well because your help was invaluable, about 60% of frameset.el non-empty lines are comments or docstrings; so this accusation is particularly amusing...) > If it can be OK in your opinion, then we can make the effort to help > users by adding it. It's about doing the right thing. Does that mean > "obligation" to you? Just because something is not obligatory and > enforced somehow, that does not mean that it should not be done. I like how you apparently think that adding stuff to a docstring has no cost and it's always valuable. Irrelevant things add complexity and verbosity. The longer a docstring is, the easier is for someone to skip important bits lost among the verbiage. > Whether you call it "obligation" or not, we can, and so we should, Again... > There is really no reason not to share this info > with those for whom the product is developed. It just helps. Yeah, it is quite clear that you think so. J From debbugs-submit-bounces@debbugs.gnu.org Sat Feb 01 02:38:57 2014 Received: (at control) by debbugs.gnu.org; 1 Feb 2014 07:38:58 +0000 Received: from localhost ([127.0.0.1]:43796 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1W9VAH-0003ql-13 for submit@debbugs.gnu.org; Sat, 01 Feb 2014 02:38:57 -0500 Received: from hermes.netfonds.no ([80.91.224.195]:58195) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1W9VAB-0003qa-7P for control@debbugs.gnu.org; Sat, 01 Feb 2014 02:38:52 -0500 Received: from [204.14.154.233] (helo=building.gnus.org) by hermes.netfonds.no with esmtpsa (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.72) (envelope-from ) id 1W9V9x-0002D0-1l for control@debbugs.gnu.org; Sat, 01 Feb 2014 08:38:37 +0100 Date: Fri, 31 Jan 2014 23:37:45 -0800 Message-Id: <8738k3p9km.fsf@building.gnus.org> To: control@debbugs.gnu.org From: Lars Ingebrigtsen Subject: control message for bug #15116 X-MailScanner-ID: 1W9V9x-0002D0-1l X-Netfonds-MailScanner: Found to be clean X-Netfonds-MailScanner-From: larsi@gnus.org MailScanner-NULL-Check: 1391845118.20421@ZFfps2bMAMxS+d1XSWZUqA X-Spam-Status: No X-Spam-Score: 0.0 (/) X-Debbugs-Envelope-To: control X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: debbugs-submit-bounces@debbugs.gnu.org Sender: "Debbugs-submit" X-Spam-Score: 0.0 (/) close 15116