guile-user Digest, Vol 189, Issue 4

[Zelphir Kaltstahl]

guile-***@gnu.org > Subject: Re: How to write documentation comments
for procedures? > Message-ID: <***@tuxteam.de> >
Content-Type: text/plain; charset=utf-8; x-action=pgp-signed >

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
(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
(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.

(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.
  GNU Guile 2.0.13
  ;; [...]
  ... "A simple function"
  ... "with a funny docstring"
  ... "which is actually three"
  ... (+ x y))
  ;; OK, can define...
  $1 = 7
  ;; and works! (but see below)
  $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.

[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.