Re: How to write documentation comments for procedures?

[Arne Babenhauserheide]

Arun Isaac <address@hidden> writes:

>> It still makes the second and later lines not indented though
>> (starting at position 0, while the first line is indented, not
>> starting at 0).
>
> Looking at the guile source code, the lack of indentation in the second
> and later lines seems to be the convention. So, I don't think this is a
> problem. Something like the following is fine.
>
> (define (foo arg)
>   "This is the first line.
> This is the second line."
>   #t)

This is what I do, too.

Note also that you can add *data* to the procedure, too, by adding a
literal array after the docstring. I use that for the equivalent of
Python doctests, but without the brittleness of writing stringly code:

    (define (example)
       "Testing doctests"
       #((tests ('mytest
              (test-assert #t)
              (test-assert #f))))
       #f)

- Example:
  
https://bitbucket.org/ArneBab/wisp/src/7501dc0db3f8cebf49b48634719ab82b4a509a79/examples/doctests-test.scm
- Doctest-runner:
  
https://bitbucket.org/ArneBab/wisp/src/7501dc0db3f8cebf49b48634719ab82b4a509a79/examples/doctests.scm

Best wishes,
Arne
--
Unpolitisch sein
heißt politisch sein
ohne es zu merken

signature.asc
Description: PGP signature