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 ';;'):

  address@hidden:~$ 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-----