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 11:37:20 -0700 (PDT) Message-ID: References: <1e335257-878b-4e7a-88d2-be252422b045@default> 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 1376764703 31147 80.91.229.3 (17 Aug 2013 18:38:23 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 17 Aug 2013 18:38: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 20:38: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 1VAlOK-0007W8-B2 for geb-bug-gnu-emacs@m.gmane.org; Sat, 17 Aug 2013 20:38:24 +0200 Original-Received: from localhost ([::1]:36714 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VAlOJ-00079J-Eb for geb-bug-gnu-emacs@m.gmane.org; Sat, 17 Aug 2013 14:38:23 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:48208) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VAlO8-000789-3O for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 14:38:20 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VAlNz-00041z-6x for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 14:38:12 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:42861) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VAlNz-00041s-21 for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 14:38:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1VAlNy-0002fv-Qx for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 14:38: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 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 Original-Received: via spool by 15116-submit@debbugs.gnu.org id=B15116.137676465510238 (code B ref 15116); Sat, 17 Aug 2013 18:38:02 +0000 Original-Received: (at 15116) by debbugs.gnu.org; 17 Aug 2013 18:37:35 +0000 Original-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 Original-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 Original-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 Original-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 Original-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 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:77473 Archived-At: > > 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.)