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: Sat, 17 Aug 2013 19:44:41 +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 1376761577 1895 80.91.229.3 (17 Aug 2013 17:46:17 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 17 Aug 2013 17:46:17 +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 Sat Aug 17 19:46:19 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 1VAkZu-0006yw-2u for geb-bug-gnu-emacs@m.gmane.org; Sat, 17 Aug 2013 19:46:18 +0200 Original-Received: from localhost ([::1]:36617 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VAkZt-0001BI-PE for geb-bug-gnu-emacs@m.gmane.org; Sat, 17 Aug 2013 13:46:17 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:41060) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VAkZl-0001B3-EM for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 13:46:14 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VAkZe-0006L9-PE for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 13:46:09 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:42810) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VAkZe-0006L4-LN for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 13:46:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1VAkZe-0001CA-99 for bug-gnu-emacs@gnu.org; Sat, 17 Aug 2013 13:46: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: 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 Original-Received: via spool by 15116-submit@debbugs.gnu.org id=B15116.13767615303117 (code B ref 15116); Sat, 17 Aug 2013 17:46:02 +0000 Original-Received: (at 15116) by debbugs.gnu.org; 17 Aug 2013 17:45:30 +0000 Original-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 Original-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 Original-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) Original-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> 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:77472 Archived-At: 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