Re: procedure docstrings / documentation

[tantalum <sph@posteo.eu>]

i don't know of common conventions, but here is what i do:
* i don't repeat the procedure name and parameter names because that can 
be queried at run-time or automatically extracted
* most of the time i write a type signature in the first line of 
docstrings because i find that information useful
* i insert newlines to limit the text width. my editor does not wrap it 
while keeping indent or otherwise formats it
* subsequent lines get one extra space at the beginning to offset the 
initial doublequote of the string literal
* i use a period to mark the end of sentences, but not after the type 
signature or the last word
* in terms of markup i stick to plaintext and indented blocks for 
sections. but texinfo (i think that is it?) is used in guile code as far 
as i know to mark variable names for example, which then get special 
formatting or become part of an index when the documentation is created 
from it

here is an example of a docstring in the way i would write it currently:

(define (test a b)
   "integer string -> integer
    text that describes this procedure,
    multiline as needed"
   (+ a (string-length b)))

i think it is nice to have an example for calling the procedure in the 
docstring.
     "example call: (interleave (list 1 2 3) 4) -> (1 4 2 4 3)"

another thing that i do for documentation in modules is that i export a 
binding with a predictable name, for example if the module is (my 
module-x) i export my-module-x-description and define it like this:

(define my-module-x-description "this module helps with x.
   syntax
     quote-odd :: any ... -> list
       quotes each second argument starting from the first and creates a 
list.
       example: (quote-odd a b c d) -> (list (quote a) b (quote c) d)
   data structures
     file-info: ((integer:mtime . string:path) ...)")

because i don't know how to add docstrings to syntax definitions, i 
document exported syntax in this way.


> Is there any convention on content/formatting for a procedure
> docstring? E.g., should I repeat the procedure name and arguments?
> Should I insert newlines to maintain a certain text width?

> I'm not really clear on how document is done in Guile, overall. I see
> Gieser has ways to look up documention for some procedures/modules, but
> it doesn't seem to pull that information from the docstring, at least
> not my docstrings.