From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Panicz Maciej Godek Newsgroups: gmane.lisp.guile.devel Subject: Re: Docstring as only form in a function Date: Thu, 20 Feb 2014 18:40:09 +0100 Message-ID: References: <877g8pk9dv.wl%arne_bab@web.de> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 X-Trace: ger.gmane.org 1392918009 23381 80.91.229.3 (20 Feb 2014 17:40:09 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Thu, 20 Feb 2014 17:40:09 +0000 (UTC) Cc: guile-devel To: arne_bab@web.de Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Thu Feb 20 18:40:18 2014 Return-path: Envelope-to: guile-devel@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 1WGXbd-0006je-N9 for guile-devel@m.gmane.org; Thu, 20 Feb 2014 18:40:17 +0100 Original-Received: from localhost ([::1]:39918 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WGXbd-0000g6-6V for guile-devel@m.gmane.org; Thu, 20 Feb 2014 12:40:17 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:38867) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WGXbX-0000fy-M9 for guile-devel@gnu.org; Thu, 20 Feb 2014 12:40:12 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WGXbW-0006c7-Mm for guile-devel@gnu.org; Thu, 20 Feb 2014 12:40:11 -0500 Original-Received: from mail-ve0-x22a.google.com ([2607:f8b0:400c:c01::22a]:63041) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WGXbW-0006by-IM for guile-devel@gnu.org; Thu, 20 Feb 2014 12:40:10 -0500 Original-Received: by mail-ve0-f170.google.com with SMTP id oz11so2166608veb.15 for ; Thu, 20 Feb 2014 09:40:09 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type; bh=jTt9f3o9zZ8cWjz3QCNm447SJihMhTElT1ZCDmEkRpk=; b=DD3Psx96i+2d7gcHkO6GcoyLQ//eYr1rYa/XT82gXPtNNUfQR9etfvTv0Btre5G/JK 55cKq240zxWgYUWmjnbn3hQBk1duQasodkAR8b+Z24twgwIfCXXKLnDyRkUrf96nK/qw KDbTAyxCBASZB+BraXiDwVmiXhzVAu7xer2phU8sVU+fP54PEqIatxy6qqp/q4u/naWJ P4fQAdDa550AZgrQvNJxl5s8BVz7Kc0RgsfPSAyWE2fCRkRCD90L0SPjj5yXcPEk8ZgY p4GHLRL1L59gvgjua13Q9gbJmLTXgk15T+Wx0WMxBsbExfTsHAJ5sWS6rnbwihB8eSRj QAaQ== X-Received: by 10.52.248.138 with SMTP id ym10mr1500693vdc.18.1392918009702; Thu, 20 Feb 2014 09:40:09 -0800 (PST) Original-Received: by 10.220.222.197 with HTTP; Thu, 20 Feb 2014 09:40:09 -0800 (PST) In-Reply-To: <877g8pk9dv.wl%arne_bab@web.de> X-detected-operating-system: by eggs.gnu.org: Error: Malformed IPv6 address (bad octet value). X-Received-From: 2607:f8b0:400c:c01::22a X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Developers list for Guile, the GNU extensibility library" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Original-Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.lisp.guile.devel:16899 Archived-At: 2014-02-20 17:59 GMT+01:00 Arne Babenhauserheide : > Hi, > > I recently experimented with docstrings, and I stumbled over not being > able to define a function which only has a docstring as body: > > > (define (foo) > "bar") > > (procedure-documentation foo) > => #f > > Adding a form makes the string act as docstring: > > (define (foo) > "bar" > #f) > > (procedure-documentation foo) > => "bar" > > I feel that this is inconsistent, which hurts even more, because it > breaks for the simplest showcase of docstrings. I feel that this is the desired behaviour. According to the semantics of Scheme, (define (foo) "bar") defines a thunk that evaluates to "bar". This makes a lot of sense, and modifying that behaviour would be very surprising. > My use case for using docstrings like this is that when I start writing > a function, I begin with the docstring. There I explain what I want to > do. Then I commit. Then I implement the function. So you can either do (define (new-foo) "function that baz the bar" #f) or even better, (define (new-foo) "function that baz the bar" (throw 'not-implemented)) > We already discussed in #guile @ freenode, that it is simple to add a > dummy-body to make the docstring work. To me that feels like a > cludge. And I was asked to move the discussion here. This would completely reverse the priorities. For the evaluator, it's the value of an expression that is important, and a docstring is something optional. It would be very misleading to have a function that has a docstring but has no body. Note that this is illegal: (define (dummy-function)) On the other hand, a function that only returns a string is rather trivial and hardly needs a documentation. > A reason for not wanting a string as the only part of the body to be > seen as docstring are that this would make it harder to write > functions which only return a string without giving them their return > value as docstring. This would then require this: > > (define (foo) > #f > "bar") > > > I think it would be more consistent to have the first form of the body > double as a docstring if it is a string. I don't see any point in this. In a real program you'll never have anything like that: (define (a-very-self-descriptive-function) "this is a function that returns this string, and besides does nothing else") If function stubs are to be the only argument, then I'd rather suggest you to change your habits. Also, if you really need to provide a docsting for a function that only returns a string, it would be much better to do: (define (a-function-that-returns-a-string-foo) "this function returns a string 'foo'" "foo") Your suggestion smells like a dirty hack, and the only motivation is to provide a documentation for functions that have no bodies -- which is wrong. > The current behaviour is that if the first form in the function is a > string, it is not part of the body - except if the body would > otherwise be empty. > > > What do you think? I oppose. That would be very misleading and it makes no sense in real (or ready) programs. Best regards, M.