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
