Re: how authors of add-on modules can package documentation

[Evan Prodromou]

>>>>> "NWVD" == Neil W Van Dyke <address@hidden> writes:

    NWVD> If anyone is thinking about different ways that authors of
    NWVD> reusable Guile add-on modules can document their code, we
    NWVD> should compare notes.

So, as a module author, I have been thinking about this quite a bit
myself. I really, really think that there should be a "standard" way
to write documentation for Guile, embedded into the code, as javadoc
is for Java, or pod for Perl, or other stuff for other languages.

There should be a tool to extract that documentation automatically to
static formats, such as (as you said) texinfo, plus a *roff file for
man pages. In addition, the documentation should be available in Guile
interactive sessions through the (help) facility or something like
it. A user shouldn't have to care whether a function was defined in
guile-core or by Evan Prodromou when asking for (help).

In any system, function signatures should be grabbed automatically for
basic function definition formats [(define (foo x) ...),
(define-public (foo x) ...), (define foo (lambda (x) ...))]. This
should be axiomatic. I'd personally like to see GOOPS (define-class)
and (define-method) stuff grabbed automatically, too, but that's just
me.

The hard part is getting description documentation -- the author's
description of what a function does, what it's for, what it returns,
and what to look out for, etc. This is a little harder to figure out
where it is and what it's related to.

I think there are several ways to have embedded documentation:

    1. The traditional Lispy ; commenting style. Old-schoolers know
       that a four-semicolon comment (;;;;) introduces a description
       of the file in general, three semicolons (;;;) is a
       per-definition (function or variable) description, two semis
       (;;) for a comment on its own line and one semi (;) for an
       in-line comment.

       It would be relatively easy for a text processor to grab
       foursies to make them the file description, and threesies to
       associate them with the next variable or function. It'd be kind
       of hard to do for interactive sessions, however, since normally
       comments are, after all, thrown away.

       Also, there's a big problem with false positives, as not all
       programmers follow this practice.

    2. The documentation string. This is also pretty traditional for
       Lispers, and it's a simple enough way to put in a description
       of whatever format and length.

       I think the problem with docstrings is that there's not really
       a good way to attach one to a file or to a variable, much less
       to a GOOPS class or method. So any embedded overview, or
       details for non-function interface items, are lost.

    3. "Special" comments or structures. These would be new
       Guile-specific mechanisms, like, say:

                   ; {doc-comment}

                   ; {/doc-comment}

       Or even 

                  (define-documented (func #:desc does something
                                           #:throws bounds-exception
                                           (x #:desc first param)
                                           (y #:desc second param)))

       I think that this would probably be easiest to process, but
       would require a lot of hassle for the author.

Of these three, I like the semi-colon format the best, but I dunno.

Regardless of how it's done, I think a Suggested Documentation Format
is something that's going to have to happen sooner rather than later,
or diverging de facto stuff will happen (or, worse, no documentation
at all).

~ESP

P.S. As to man pages: I think a suggested module.3guile is
imperative. Man pages make the world go round, after all, and I don't
think texinfo puts them out.

-- 
Evan Prodromou
address@hidden