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#15116: 24.3.50; doc of `set-match-data' Date: Sat, 17 Aug 2013 09:14:50 -0700 (PDT) Message-ID: <1e335257-878b-4e7a-88d2-be252422b045@default> References: NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1376756183 14321 80.91.229.3 (17 Aug 2013 16:16:23 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 17 Aug 2013 16:16:23 +0000 (UTC) Cc: 15116@debbugs.gnu.org To: Juanma Barranquero Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Aug 17 18:16:24 2013 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1VAjAu-0000i7-Ai for geb-bug-gnu-emacs@m.gmane.org; Sat, 17 Aug 2013 18:16:24 +0200 Original-Received: from localhost ([::1]:36464 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VAjAt-0001Oa-Gy for geb-bug-gnu-emacs@m.gmane.org; Sat, 17 Aug 2013 12:16:23 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:50662) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VAjAh-0001DU-DL for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 12:16:21 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VAjAY-0003PM-Rg for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 12:16:11 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:42634) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VAjAY-0003PG-ON for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 12:16:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1VAjAX-00053Q-TA for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 12:16:02 -0400 X-Loop: help-debbugs@gnu.org 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: Original-Received: via spool by 15116-submit@debbugs.gnu.org id=B15116.137675610219321 (code B ref 15116); Sat, 17 Aug 2013 16:16:01 +0000 Original-Received: (at 15116) by debbugs.gnu.org; 17 Aug 2013 16:15:02 +0000 Original-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 Original-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 Original-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 Original-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 Original-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 In-Reply-To: X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6680.5000 (x86)] X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x 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:77466 Archived-At: > > 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".