From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Newsgroups: gmane.lisp.guile.user Subject: Re: How to write documentation comments for procedures? Date: Sun, 5 Aug 2018 18:22:49 +0200 Message-ID: <20180805162249.GA30674@tuxteam.de> References: <31082a15-b9f4-aba2-6a2b-2e784cf55406@gmail.com> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; x-action=pgp-signed Content-Transfer-Encoding: 8bit X-Trace: blaine.gmane.org 1533486081 29855 195.159.176.226 (5 Aug 2018 16:21:21 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 5 Aug 2018 16:21:21 +0000 (UTC) User-Agent: Mutt/1.5.21 (2010-09-15) To: guile-user@gnu.org Original-X-From: guile-user-bounces+guile-user=m.gmane.org@gnu.org Sun Aug 05 18:21:16 2018 Return-path: Envelope-to: guile-user@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fmLmN-0007en-V7 for guile-user@m.gmane.org; Sun, 05 Aug 2018 18:21:16 +0200 Original-Received: from localhost ([::1]:59218 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fmLoS-0003Mk-PT for guile-user@m.gmane.org; Sun, 05 Aug 2018 12:23:24 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:47970) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fmLo4-0003MM-03 for guile-user@gnu.org; Sun, 05 Aug 2018 12:23:01 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fmLo0-0006tf-Ri for guile-user@gnu.org; Sun, 05 Aug 2018 12:22:59 -0400 Original-Received: from mail.tuxteam.de ([5.199.139.25]:36763) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fmLo0-0006pZ-Ha for guile-user@gnu.org; Sun, 05 Aug 2018 12:22:56 -0400 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=tuxteam.de; s=mail; h=From:In-Reply-To:Content-Transfer-Encoding:Content-Type:MIME-Version:References:Message-ID:Subject:To:Date; bh=biQ1ir13P75nfrZgBDKyAZIwtJ+IobHvmWi1OA/1API=; b=l7Uwp4iIasCx5HenHilobHABRDk/2osxwh2r1Ine9tF0stgheQZ7v4gi6Bf7PEh5+T+AzkxIFJcP3DUzMzuSo9LescEzPSN95b+8nnrHGoO2SaabK7qAPppD50q6HIErOmCyL7pb3XvyQIUeBmzc8/ewBaKdwG/V8Zmfsj11O4eAYB2fy38hCh409gmsRFiYkIBsHeLY5CKywRefw48jvgk9CEHo/fM0OCroso6oCPz3awS7O10QqDiV+zCHF2TBGykHnGXACRorLxczd3y+xRWHAnwMX+w5tAmH+m4tckFXhlx/YoRJNHKyapoUD6XbuWeBJYUww5cpuNxv3LaUjA==; Original-Received: from tomas by mail.tuxteam.de with local (Exim 4.80) (envelope-from ) id 1fmLnt-0000qL-8x for guile-user@gnu.org; Sun, 05 Aug 2018 18:22:49 +0200 In-Reply-To: <31082a15-b9f4-aba2-6a2b-2e784cf55406@gmail.com> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [fuzzy] X-Received-From: 5.199.139.25 X-BeenThere: guile-user@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: General Guile related discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guile-user-bounces+guile-user=m.gmane.org@gnu.org Original-Sender: "guile-user" Xref: news.gmane.org gmane.lisp.guile.user:14725 Archived-At: -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Sun, Aug 05, 2018 at 03:27:33PM +0200, Zelphir Kaltstahl wrote: > Hello Guile user list members, > > How do you write documentation strings for procedures? What are the > conventions for describing arguments? > > Since only the last expression is returned from a procedure, one can use > normal strings as a first thing in a procedure as follows: > > (define (proc a b c) >   "comment here" >   (+ a b c)) > > However, when I have a longer explanation for a procedure, longer than a > single line of certain length, then the line will softly wrap in editors > and the explanation will continue on the next line at the beginning > usually. Also it will be a very long line, longer than most conventions > for line lengths. For example: > > (define (proc a b c) >   "comment here comment here comment here comment here comment here > comment here comment here comment here comment here comment here comment > here comment here comment here ..." >   (+ a b c)) Looking at the existing sources in Guile, this seems to be the convention (it coincides with the way it's done in other Lisps). I'd think this is OK. > So I could make it multiple strings instead: > > (define (proc a b c) >   "comment here comment here comment here" >   "comment here comment here comment here" >   "comment here comment here comment here" >   "comment here comment here ..." >   (+ a b c)) > > Would that work for tools, which look at code and produce documentation > websites though? Would they be aware of multiple strings being the doc > comment? I'd expect the parser to "get this wrong". The first string would be seen as the doc string, I'd expect the others to form part of the procedure body. The tools would be in the same position, I guess. Let's give it a try (my interspersed comments prefixed with ';;'): tomas@trotzki:~$ guile GNU Guile 2.0.13 ;; [...] scheme@(guile-user)> (define (foo x y) ... "A simple function" ... "with a funny docstring" ... "which is actually three" ... (+ x y)) ;; OK, can define... scheme@(guile-user)> (foo 3 4) $1 = 7 ;; and works! (but see below) scheme@(guile-user)> (procedure-documentation foo) $2 = "A simple function" ;; alas, the "docstring" is just the first one... Now why does the function "work"? Actually, the expressions in the function body are wrapped in a "progn", meaning that they are evaluated in order, and only the last expression's value is is the function's value. So (conceptually, unless the optimizer notices), foo first evaluates "with a funny docstring", which evaluates to itself, throws the result away, then goes on... you guess the rest. > I could also go for normal comments using ;; or even #||# regions, but > the same questions arises again: What would tools make of this? Would > they recognize it as doc comments? Comments are quite different beasts from docstrings. The docstring gets attached to the function object (so a function without source, which you build "on the fly" at runtime) can have a docstring. Source comments are attached to the source. > How do you handle this? And what tools are there to generate > documentation websites or PDF or things like that? This is bigger fish. I'll defer to smarter people here :-) Cheers - -- tomás -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.12 (GNU/Linux) iEYEARECAAYFAltnJFkACgkQBcgs9XrR2kYxRQCfWb7ko+CTFPlGOWe35qWz48I6 QloAnRzb57+60bRuX2R74TnyKDQi5Og5 =FH2q -----END PGP SIGNATURE-----