[racket] comments on format for api documentation embedded in modules

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.