[Jscheme-user] schemedoc?

[Ken A. <kan...@bb...>]

Mike Thome (a substantial Common Lisp hacker until he was asked to write in Java) has just started using JScheme to help us do some semantic web stuff.

One comment he made is basically "one good thing that Java did was Javadoc".
He also mentioned that while the JScheme builtins and modules are documented other cool things like map*, sort, ... are not.  We've heard calls for documentation before too.

I've tried to put hints in the package.html in each directory but i don't know if anyone has ever looked there.  

So maybe we should come schemedoc heres a LAML version:
http://www.cs.auc.dk/~normark/schemedoc/

I'd the simplest thing that would be useful to a new user. The first step might be to cat all the scheme source code into an .html page (with some reformatting) so the desperate user can search for something that might help.

I'd prefer to keep the special notation an ceremony to a minimum.

The minimum would be comment block or quasistring at the top of the file to give an overview.  and for each define something like
(define (f x)
  ;; f is this really cool function of int x.
  ...)

The comment could be a string or quasistring too so it would be available with apropos and describe in a running JScheme.  This is what CL did, but it also makes the system bigger, so it was optional.  But it ment you could generate documentation for your application pretty easily.

SLIB has picked another documentation style. 

At a minimum there should be some documentation of the scheme in jscheme.jar.

k