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#15117: 24.3.50; doc of `(forward|backward)-*': state return value Date: Tue, 11 Feb 2014 18:36:46 +0100 Message-ID: References: <1dc76f7a-5481-41df-b976-ec22229d7283@default> <874n4a42f0.fsf@building.gnus.org> <1281d0fd-77cb-45e2-b99d-f4ad24b0fc4e@default> <2fefcbaf-9417-4f57-93af-490ea73aea98@default> <68a64949-d801-4d09-8dc8-4b6ae0824855@default> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 X-Trace: ger.gmane.org 1392140291 4200 80.91.229.3 (11 Feb 2014 17:38:11 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 11 Feb 2014 17:38:11 +0000 (UTC) Cc: 15117@debbugs.gnu.org, Lars Ingebrigtsen To: Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Feb 11 18:38:18 2014 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 1WDHHl-00046q-JH for geb-bug-gnu-emacs@m.gmane.org; Tue, 11 Feb 2014 18:38:17 +0100 Original-Received: from localhost ([::1]:35152 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WDHHl-0002u0-0D for geb-bug-gnu-emacs@m.gmane.org; Tue, 11 Feb 2014 12:38:17 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:58719) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WDHHd-0002tX-5Y for bug-gnu-emacs@gnu.org; Tue, 11 Feb 2014 12:38:13 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WDHHY-0002Tj-IT for bug-gnu-emacs@gnu.org; Tue, 11 Feb 2014 12:38:09 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:46562) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WDHHY-0002Tf-El for bug-gnu-emacs@gnu.org; Tue, 11 Feb 2014 12:38:04 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1WDHHX-0002Vh-Hs for bug-gnu-emacs@gnu.org; Tue, 11 Feb 2014 12:38:03 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Juanma Barranquero Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 11 Feb 2014 17:38:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 15117 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: wontfix Original-Received: via spool by 15117-submit@debbugs.gnu.org id=B15117.13921402579611 (code B ref 15117); Tue, 11 Feb 2014 17:38:02 +0000 Original-Received: (at 15117) by debbugs.gnu.org; 11 Feb 2014 17:37:37 +0000 Original-Received: from localhost ([127.0.0.1]:47744 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WDHH6-0002Uw-1q for submit@debbugs.gnu.org; Tue, 11 Feb 2014 12:37:36 -0500 Original-Received: from mail-yh0-f42.google.com ([209.85.213.42]:57642) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WDHH2-0002Ud-NZ for 15117@debbugs.gnu.org; Tue, 11 Feb 2014 12:37:33 -0500 Original-Received: by mail-yh0-f42.google.com with SMTP id a41so7191098yho.29 for <15117@debbugs.gnu.org>; Tue, 11 Feb 2014 09:37:27 -0800 (PST) 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=S2k+S5svAbq2Ut2z2C5VpZzmLGuOlTupu5AJBg3DDdo=; b=nvMWgEf0PttldYNGh3wEzSN7tY6wHioYENwct6Km5qaygXsP+FbkgQ1rV/RbzyF18r ps1/+JMGB3wZ4r46L6uY/k19A0OWZHyLAOuR3+PVtm0gJf77UliVvkQpgqi4q6TsCQzP 0Fc8mQVDupXZl6NXl8tWqUSSvwUcmHx0ZA625XsZ/oUQiWpKgwjZRSTEy7lPMnoRV0fq j+eZWBVJ5Qf0bi0DxiL11ocQD7pwR9U7NM6Rbbf6knkST2l1SIvn3p9ausuQ2qnAbXTQ VDBIf3Sftu3slXVY6g/XMOqAqBpcUbdKXUHiIpZT7ISYTsin25RzHDcapX+g/0sgWqMs nCng== X-Received: by 10.236.144.103 with SMTP id m67mr1689677yhj.146.1392140246958; Tue, 11 Feb 2014 09:37:26 -0800 (PST) Original-Received: by 10.170.84.65 with HTTP; Tue, 11 Feb 2014 09:36:46 -0800 (PST) In-Reply-To: <68a64949-d801-4d09-8dc8-4b6ae0824855@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:85394 Archived-At: On Tue, Feb 11, 2014 at 7:43 AM, Drew Adams wrote: > That is anyway *not* a criterion I use for whether a Lisp > function should have a defined and documented return value. The only criteria that make sense IMHO about whether a function should have a defined and documented return value are: - That the return value is useful and non-trivial. - That it is somewhat related to the function's purpose. As an example, goto-char has a documented return value, POSITION, identical to its only argument. I suppose it is so for historical reasons and I'm not proposing to undocument it, but if goto-char were introduced now, I would, because the only thing you gain from it is saving a `let' binding every now and then (perhaps 100 times out of ~12,000 calls to goto-char in the sources). > Agreed; it is. And the resulting position is thus an important part > of its effect. And it is handy to use that value directly. The result of goto-char is NOT "the resulting position". Try (with-temp-buffer (goto-char 1000)) => 1000 or (let ((p (point-marker))) (eq p (goto-char p))) => t The result of goto-char is *its argument*, even if it does not make sense. > Are you arguing not to document `goto-char's return value, as well? > And so to discourage its use? After all, one doesn't need to depend > on it - it's certainly enough to depend on the side effect and then > call `point' to get the new position. As said above, I would, if it were a new function, yes. > If so, go for it. Then what have you gained? Greater liberty > for the implementation to change? Bof. More readable code? Bof. Your "bof" is my "hell, yeah". > Code that is more functional or side-effect free? Certainly not. I wouldn't presume to make a side-effect function side-effect free. That'd be weird ;-) > Whether something constitutes a "side effect" > is relative. I don't think so. > 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: "This function is used only for its side > effects; the return value is undefined." This is Lisp, not C - > return values are the norm, not the exception. Not documenting a return value is, in fact, a way of saying "this function is used only for its side effects; the return value is undefined". It's just that it is a way of saying it that you dislike, but it has a long history. > It is not because a function performs side effects that its > return value should not be counted on (and so documented). No, it is because it is trivial, or irrelevant, or an accident of implementation. > It's all about what we want for programmers. Should they get > a useful return value for the given function or not? That's > the only question. The answer to that question is already there: some do (return a useful value), some don't. What you're saying instead is that, in your opinion, *most* functions should have its return value documented, because that's more "lispy". But Elisp is not just a lisp, it's the high-level implementation language of a text editor, and as such, there are many functions intended to produce side effects in the text; that they return a value is a consequence of these functions being implemented in lisp, which does not have a concept of not returning anything at all. > Consider `when', for instance. I, for one, adopt the convention > often used with Common Lisp of NOT using the return value. Why? > To signal the programmer intention that what is happening is for > the side effects and not for the return value - i.e., that in > that particular context, the return value is not important. IOW, > this is to help readers of the code; nothing more. I do, too. But in fact, I think that function is an argument for my position, not yours, exactly because of this: > If you were to argue that we should not document the return > value of `when' or `unless' you would get no argument from > me. (Well, actually, I would again suggest saying explicitly > that one should not count on the return value.) Exactly. I would prefer that `when' and `unless' had their return values undefined, and people had to use (if X Y nil) or (if X nil Y). > In the case of the motion functions, there is a useful value > to return: the destination position. And my question about > that is "Why not?". I've seen no response to that question, > so far. Why not? See above. If the function is moving the point in a non trivial way, it makes sense to return the new position. If not, not. There's nothing special about motion functions. > I'm not sure the resulting position is particularly useful in > the case of `recenter', but if you proposed returning it and > documenting that, I might not object. Why not? I don't have > a great reason why not for `recenter' - do you? recenter does not move the point. It could return `point', but, what for? > Look at those functions. See if you would really argue that > we should not document their return values and let users > depend on them. See if you want to shout "side effects!" > or some other battle cry as a reason for making such a change. Drew, I didn't enter the discussion to defend function purity, just to try to understand why did you define obvious side-effects as "no side effects". That said, I do think that in many cases documenting the return value has as a net negative effect in that it does not add value and limits implementation. But there's nothing new there, we've had this discussion before. > Please answer the > question of why we should not let users write code that > counts on the moved-to position as a return value. I think it is a good idea to encourage the users to use functions that return the position as their *main* effect. J