Re: guile-user Digest, Vol 189, Issue 4

Re: guile-user Digest, Vol 189, Issue 4

[Zelphir Kaltstahl]

On 06.08.2018 18:00, guile-user-request@gnu.org wrote:
> Message: 1 > Date: Sun, 5 Aug 2018 18:22:49 +0200 > From: <tomas@tuxteam.de> > To:
guile-user@gnu.org > Subject: Re: How to write documentation comments
for procedures? > Message-ID: <20180805162249.GA30674@tuxteam.de> >
Content-Type: text/plain; charset=utf-8; x-action=pgp-signed >
> 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

Thanks for the information. I did not know the procedure-documentation
procedure. I guess I'll go with the one long docstring which has line
breaks style then. This will also be easiest to write using that
fill-paragraph shortcut.

Re: guile-user Digest, Vol 189, Issue 4

[Arun Isaac]

> I did not know the procedure-documentation procedure. I guess I'll go
> with the one long docstring which has line breaks style then. This
> will also be easiest to write using that fill-paragraph shortcut.

Just one more minor addition. You can break up the docstring into
paragraphs as well. You don't have to keep the entire docstring as a
single paragraph. Breaking up a large docstring into paragraphs helps
readability. You can find many examples of this in the guile source
code.