[racket] in-line documentation program? Like Javadoc or Doxygen

On Tue, 2011-04-05 at 17:24 -0400, Neil Van Dyke wrote:
> Charles Hixson wrote at 04/05/2011 04:44 PM:
> > I was really looking for something simple like Doxygen or Javadoc.  
> > Something that steps through the code, looks at comments, and pulls 
> > out of marked comments into a documentation file.   (Well, the 
> > programs might not be simple, but how you mark-up the code for them is.)
> 
> There a few such tools floating around for Scheme, but none I've seen is 
> ideal for Racket.
> 
> Two Racket-specific things that this tool should do: (1) Use Typed 
> Racket contracts as part of the documentation; and (2) Use Scribble as 
> the text markup language.

Ideally the tool would also use contracts as documention, as well as use
unit tests for examples.

There are also other useful extractable things like module hierarchy,
defined types (struct, class, ...), macros etc. that should be
supported.

I've thought about making such a tool because in my projects I need some
way to observe the static structure of the program. There is hardly any
support for organizing a project with the existing tools.

What I've come up with so far is just a scanner that goes through your
directory and lists all the types and modules it finds and draws graphs
with Graphviz with the hierarchy.

Here's one picture generated with it:
http://dl.dropbox.com/u/17629796/Structure.png

And here's another that shows what could come out as documentation from
RackUnit if there was a nice integration.
http://dl.dropbox.com/u/17629796/RackUnit.png

I bet there are a lot of "low-hanging fruits" that can be picked easily.
Ideally Racket distribution would include tools for walking through your
source code in a standard way and people like me could build tools to
show the data in interesting ways. Of course in a flexible language like
Racket, it's sometimes impossible, but there's a lot to do with even
simple constructs.

-Markku

> 
> For now, I am still using an old, unreleased tool for Scheme and 
> Texinfo, which is no longer ideal.  My latest excuse for not writing the 
> new tool yet is that I'm waiting for Typed Racket to support keyword 
> args, so that I can get maximum immediate gratification if I blow a 
> weekend on this.
>