How to write documentation comments for procedures?

How to write documentation comments for procedures?

[Zelphir Kaltstahl]

Hello Guile user list members,

How do you write documentation strings for procedures? What are the
conventions for describing arguments?

Since only the last expression is returned from a procedure, one can use
normal strings as a first thing in a procedure as follows:

(define (proc a b c)
  "comment here"
  (+ a b c))

However, when I have a longer explanation for a procedure, longer than a
single line of certain length, then the line will softly wrap in editors
and the explanation will continue on the next line at the beginning
usually. Also it will be a very long line, longer than most conventions
for line lengths. For example:

(define (proc a b c)
  "comment here comment here comment here comment here comment here
comment here comment here comment here comment here comment here comment
here comment here comment here ..."
  (+ a b c))

So I could make it multiple strings instead:

(define (proc a b c)
  "comment here comment here comment here"
  "comment here comment here comment here"
  "comment here comment here comment here"
  "comment here comment here ..."
  (+ a b c))

Would that work for tools, which look at code and produce documentation
websites though? Would they be aware of multiple strings being the doc
comment?

I could also go for normal comments using ;; or even #||# regions, but
the same questions arises again: What would tools make of this? Would
they recognize it as doc comments?

How do you handle this? And what tools are there to generate
documentation websites or PDF or things like that?

Regards,

Zelphir

Re: How to write documentation comments for procedures?

[tomas]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Sun, Aug 05, 2018 at 03:27:33PM +0200, Zelphir Kaltstahl wrote:
> Hello Guile user list members,
> 
> How do you write documentation strings for procedures? What are the
> conventions for describing arguments?
> 
> Since only the last expression is returned from a procedure, one can use
> normal strings as a first thing in a procedure as follows:
> 
> (define (proc a b c)
>   "comment here"
>   (+ a b c))
> 
> However, when I have a longer explanation for a procedure, longer than a
> single line of certain length, then the line will softly wrap in editors
> and the explanation will continue on the next line at the beginning
> usually. Also it will be a very long line, longer than most conventions
> for line lengths. For example:
> 
> (define (proc a b c)
>   "comment here comment here comment here comment here comment here
> comment here comment here comment here comment here comment here comment
> here comment here comment here ..."
>   (+ a b c))

Looking at the existing sources in Guile, this seems to be the
convention (it coincides with the way it's done in other
Lisps). I'd think this is OK.

> So I could make it multiple strings instead:
> 
> (define (proc a b c)
>   "comment here comment here comment here"
>   "comment here comment here comment here"
>   "comment here comment here comment here"
>   "comment here comment here ..."
>   (+ a b c))
> 
> Would that work for tools, which look at code and produce documentation
> websites though? Would they be aware of multiple strings being the doc
> comment?

I'd expect the parser to "get this wrong". The first string would be
seen as the doc string, I'd expect the others to form part of the
procedure body.

The tools would be in the same position, I guess.

Let's give it a try (my interspersed comments prefixed with ';;'):

  tomas@trotzki:~$ guile
  GNU Guile 2.0.13

  ;; [...]

  scheme@(guile-user)> (define (foo x y)
  ... "A simple function"
  ... "with a funny docstring"
  ... "which is actually three"
  ... (+ x y))

  ;; OK, can define...

  scheme@(guile-user)> (foo 3 4)
  $1 = 7

  ;; and works! (but see below)

  scheme@(guile-user)> (procedure-documentation foo)
  $2 = "A simple function"

  ;; alas, the "docstring" is just the first one...

Now why does the function "work"? Actually, the expressions
in the function body are wrapped in a "progn", meaning that
they are evaluated in order, and only the last expression's
value is is the function's value. So (conceptually, unless
the optimizer notices), foo first evaluates "with a funny docstring",
which evaluates to itself, throws the result away, then goes
on... you guess the rest.

> I could also go for normal comments using ;; or even #||# regions, but
> the same questions arises again: What would tools make of this? Would
> they recognize it as doc comments?

Comments are quite different beasts from docstrings. The docstring
gets attached to the function object (so a function without source,
which you build "on the fly" at runtime) can have a docstring.

Source comments are attached to the source.

> How do you handle this? And what tools are there to generate
> documentation websites or PDF or things like that?

This is bigger fish. I'll defer to smarter people here :-)

Cheers
- -- tomás
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.12 (GNU/Linux)

iEYEARECAAYFAltnJFkACgkQBcgs9XrR2kYxRQCfWb7ko+CTFPlGOWe35qWz48I6
QloAnRzb57+60bRuX2R74TnyKDQi5Og5
=FH2q
-----END PGP SIGNATURE-----

Re: How to write documentation comments for procedures?

[Arun Isaac]

> However, when I have a longer explanation for a procedure, longer than a
> single line of certain length, then the line will softly wrap in editors
> and the explanation will continue on the next line at the beginning
> usually.

In emacs, I find `fill-paragraph' (default keybinding of M-q) to be very
useful for wrapping long lines.

Re: How to write documentation comments for procedures?

[Zelphir Kaltstahl]

Ha, I did not know that one. 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). Anyway, knowing this shortcut would have
saved me soooo much time in many cases … Thanks.


On 06.08.2018 11:26, Arun Isaac wrote:
>> However, when I have a longer explanation for a procedure, longer than a
>> single line of certain length, then the line will softly wrap in editors
>> and the explanation will continue on the next line at the beginning
>> usually.
> In emacs, I find `fill-paragraph' (default keybinding of M-q) to be very
> useful for wrapping long lines.

Re: How to write documentation comments for procedures?

[Arun Isaac]

> 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)

Re: How to write documentation comments for procedures?

[Arne Babenhauserheide]

[-- Attachment #1: Type: text/plain, Size: 1232 bytes --]


Arun Isaac <arunisaac@systemreboot.net> 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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1076 bytes --]