How to write documentation comments for procedures?

[Zelphir Kaltstahl <zelphirkaltstahl@gmail.com>]

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))

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 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?

How do you handle this? And what tools are there to generate
documentation websites or PDF or things like that?

Regards,

Zelphir