guile-user
[Top][All Lists]
Advanced

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



reply via email to

[Prev in Thread] Current Thread [Next in Thread]