Anyone have comments on how they'd like to embed API documentation
within Racket module source code?
I've done in two ways so far, and am about to write a new tool for this,
so I have a chance to rethink it. The earlier two ways;
* The first way I did it, for generic Scheme, was in Funcelit
("functionally-illiterate programming"), which let me embed fragments of
Texinfo documentation throughout the code by prefixing each line with
";;;". Along with a few other conveniences. The main drawback was that
you couldn't encode type information, and also I wanted to be able to
use all the Scribble goodness (e.g., BNF).
* The second way I did it, for McFly in Racket, was to have a dummy
syntax form (named `doc`) that could be put most anywhere at toplevel,
and into which you could embed Scribble code. Along with a few other
conveniences (like a special form for package history, and inferring
procedure signatures in some cases). The main drawbacks were that
Scribble documentation was a little harder to read and write than
Texinfo documentation, and that the eye couldn't tell documentation and
code apart well enough (I never got around to adding syntax coloring for
this to Emacs like I did for Funcelit). (Incidentally, I ended up not
using the signature inference in practice, since I almost always ended
up writing in `racket/base` and without contracts.)
For the new tool, I'm leaning strongly towards the documentation format
being exactly like in McFly, but I'm open to comments.
Neil V.
____________________
Racket Users list:
http://lists.racket-lang.org/users
