Re: procedure docstrings / documentation

[Arne Babenhauserheide]

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