From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Juanma Barranquero Newsgroups: gmane.emacs.bugs Subject: bug#15116: 24.3.50; doc of `set-match-data' Date: Sun, 18 Aug 2013 04:06:36 +0200 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 X-Trace: ger.gmane.org 1376791692 7413 80.91.229.3 (18 Aug 2013 02:08:12 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 18 Aug 2013 02:08:12 +0000 (UTC) Cc: 15116@debbugs.gnu.org To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Aug 18 04:08:14 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 1VAsPd-0002KJ-Qr for geb-bug-gnu-emacs@m.gmane.org; Sun, 18 Aug 2013 04:08:14 +0200 Original-Received: from localhost ([::1]:37464 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VAsPc-0005XT-Om for geb-bug-gnu-emacs@m.gmane.org; Sat, 17 Aug 2013 22:08:12 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:49926) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VAsPW-0005P1-Fy for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 22:08:10 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VAsPR-0003Nw-W5 for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 22:08:06 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:43325) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VAsPR-0003Ns-S9 for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 22:08:01 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1VAsPR-0007Yv-V0 for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 22:08:02 -0400 X-Loop: help-debbugs@gnu.org 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 Original-Received: via spool by 15116-submit@debbugs.gnu.org id=B15116.137679164629007 (code B ref 15116); Sun, 18 Aug 2013 02:08:01 +0000 Original-Received: (at 15116) by debbugs.gnu.org; 18 Aug 2013 02:07:26 +0000 Original-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 Original-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 Original-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) Original-Received: by 10.14.133.15 with HTTP; Sat, 17 Aug 2013 19:06:36 -0700 (PDT) In-Reply-To: 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:77475 Archived-At: 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