guile-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: Neil Jerram
Subject: Re: how authors of add-on modules can package documentation
Date: 17 Mar 2002 23:35:17 +0000
User-agent: Gnus/5.0808 (Gnus v5.8.8) Emacs/20.7

>>>>> "Evan" == Evan Prodromou <address@hidden> writes:

>>>>> "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.

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

I haven't yet read your ideas carefully, but you might like to note
that there were a couple of mailing list threads in this area back in
February 2001:

- subject "docstring work" beginning at
  http://mail.gnu.org/pipermail/guile-devel/2001-February/001001.html

- subject "Documentation" beginning at
  http://mail.gnu.org/pipermail/guile-devel/2001-February/001154.html

I believe the consensus at the end of those threads preferred docs as
strings rather than as comments; i.e.

(define (xxx arg)
  "Do something"
  ...)

rather than

;;; Do something
(define (xxx arg)
  ...)

Oh, and don't forget i18n!

        Neil




reply via email to

[Prev in Thread] Current Thread [Next in Thread]