[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: procedure docstrings / documentation
From: |
Arne Babenhauserheide |
Subject: |
Re: procedure docstrings / documentation |
Date: |
Sun, 24 Sep 2017 08:49:05 +0200 |
Christopher Howard <address@hidden> writes:
> No thoughts related to this subject?
> On Wed, 2017-09-20 at 16:18 -0800, Christopher Howard wrote:
>> 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.
I know what I do, but I’m not sure that’s conventional.
- I insert newlines (via M-q) to keep the code short.
- I describe in the first paragraph what the procedure does, in the way
I want to read when I call (help procedure). I try to stay at one
line, but if that makes the info too bad, I use a longer paragraph.
- Then I add two newlines and additional information.
Here’s a mostly OK example:
(define (cholesky! a)
"Modifies the square matrix a to contain its cholesky decomposition.
sets a to g with a = ggT,
a is represented as list of lists."
let : : n : length a
…
(from
<https://bitbucket.org/ArneBab/wisp/src/b94c06e83108c2422bea0da8d6cf711c9cd26ce3/examples/cholesky.w#cholesky.w-54>
)
This is another example:
(define (logiota steps start stepsize)
"Create numbers evenly spread in log space"
(let*
((logstart (log (+ start 1)))
(logstep (/ (- (log (+ start (* stepsize (- steps 1)))) logstart)
(- steps 1))))
(map inexact->exact (map round (map exp (iota steps logstart
logstep ))))))
(from
<https://bitbucket.org/ArneBab/wisp/src/b94c06e83108c2422bea0da8d6cf711c9cd26ce3/examples/benchmark.w#benchmark.w-112>
)
However I think that my docstrings are rathor too short than too long.
I’m still working a way to add doctests (I plan to add them as property,
not to the docstring).
Best wishes,
Arne
--
Unpolitisch sein
heißt politisch sein
ohne es zu merken
signature.asc
Description: PGP signature