[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: procedure docstrings / documentation
From: |
tantalum |
Subject: |
Re: procedure docstrings / documentation |
Date: |
Sun, 24 Sep 2017 00:47:30 +0000 |
User-agent: |
Posteo Webmail |
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.