From: Evan Prodromou <evan@glug.org>
Subject: Re: how authors of add-on modules can package documentation
Date: Sun, 17 Mar 2002 10:41:04 -0600 [thread overview]
Message-ID: <87zo17f8pr.fsf@tyrell.bad-people-of-the-future.san-francisco.ca.us> (raw)
In-Reply-To: <15508.6444.70455.739266@winona.neilvandyke.org> ("Neil W. Van Dyke"'s message of "Sat, 16 Mar 2002 23:18:52 -0500")
>>>>> "NWVD" == Neil W Van Dyke <nwv@neilvandyke.org> 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
evan@glug.org
_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel
next prev parent reply other threads:[~2002-03-17 16:41 UTC|newest]
Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top
2002-03-17 4:18 how authors of add-on modules can package documentation Neil W. Van Dyke
2002-03-17 16:41 ` Evan Prodromou [this message]
2002-03-17 23:35 ` Neil Jerram
2002-03-17 23:45 ` Neil Jerram
2002-03-18 2:04 ` Evan Prodromou
2002-04-03 5:29 ` Thien-Thi Nguyen
2002-04-03 3:52 ` Thien-Thi Nguyen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/guile/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87zo17f8pr.fsf@tyrell.bad-people-of-the-future.san-francisco.ca.us \
--to=evan@glug.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).