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

From: Matthias Felleisen (matthias at ccs.neu.edu)
Date: Sun Apr 10 13:09:46 EDT 2011

Why do you use graphviz? Isn't the module browser giving you the 
graph that you want? 

A while ago I proposed to the dev list that we need a 'tooltip' 
thing so that the module browser shows the interface of modules
and ideally the types or contracts (these are two distinct, barely 
related ideas) of the identifiers that are exported. Jon @ Utah
started working on this and has the 'batch' version ready; I am 
not sure why he didn't finish the job. 

But in general, we welcome any and all contributions to the IDE
that people are willing to create. Ideally you should coordinate
such activities on the dev list and best of all someone on the 
inside should 'buy' into it. In the end however we want an open
architecture and contributions, that's why Robby put in APIs for
teachpacks and tools for DrRacket. 

-- Matthias






On Apr 10, 2011, at 8:07 AM, Markku Rontu wrote:

> 
> 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.
>> 
> 
> 
> _________________________________________________
>  For list-related administrative tasks:
>  http://lists.racket-lang.org/listinfo/users



Posted on the users mailing list.