unofficial mirror of guile-devel@gnu.org 
 help / color / mirror / Atom feed
From: Neil Jerram <neil@ossau.uklinux.net>
Cc: guile-devel@gnu.org
Subject: Re: how authors of add-on modules can package documentation
Date: 17 Mar 2002 23:35:17 +0000	[thread overview]
Message-ID: <m3r8mikbt6.fsf@laruns.ossau.uklinux.net> (raw)
In-Reply-To: <87zo17f8pr.fsf@tyrell.bad-people-of-the-future.san-francisco.ca.us>

>>>>> "Evan" == Evan Prodromou <evan@glug.org> writes:

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

    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


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel


  reply	other threads:[~2002-03-17 23:35 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
2002-03-17 23:35   ` Neil Jerram [this message]
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=m3r8mikbt6.fsf@laruns.ossau.uklinux.net \
    --to=neil@ossau.uklinux.net \
    --cc=guile-devel@gnu.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).