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

I've hit the noweb documentations several times, and bounced each time.

robodoc looks like it might be suitable, but I was hoping? expecting? 
that there would be some standard approach.  (With robodoc each person 
must define their own markup flags for lisp, as it's not a standardly 
supported language.  This is inferior to having a standard for what 
indicates a function name, etc.)

When I look at the examples of Scribble literate programming, they seem 
to make the code obscure in the original file.  This is not at all what 
I want.  The documentation is documentation <i>of the code</i>.  It's 
the code that's the important thing.  The documentation is just to make 
it easy to find, and to use.  Internal comments are to make it easier to 
understand in detail.  But it's the code that is primary, and anything 
that obscures it is NOT what I want.  (One of the problems I have with 
robodoc is that it's too verbose when you write it, but it's simple and 
unintrusive compared to the examples I've seen of noweb or embedded 
Scribble.)

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.)


On 04/05/2011 12:02 PM, Deren Dohoda wrote:
>
> Have you looked at literate programming tools like noweb, and the 
> literate tools in Racket?
>
> On Apr 5, 2011 2:52 PM, "Charles Hixson" <charleshixsn at earthlink.net 
> <mailto:charleshixsn at earthlink.net>> wrote:
> > Is there there a program roughly similar to doxygen or javadoc for
> > Scheme or Racket?
> >
> > I know myself to well to believe that I will document something, and
> > keep the documentation current, unless it is right next to the code
> > being documented. (It didn't work in Fortran or C when that's one of
> > the things I was being paid to do, so it's not likely to work now.) But
> > javadoc and doxygen are things I find easy to just update the
> > documentation when I change the code. If I understand correctly
> > Scribble wants the documentation to be in a separate file, so I need a
> > different method.
> >
> > From past history I prefer documentation embedded in comments preceding
> > the code item that it documents. I never did take to Python
> > documentation strings. And I'd like to be able to produce two kinds of
> > documentation: one that documents everything and one that only
> > documents externally visible items. My ideal output forms are HTML and
> > odt (OpenOffice) files.
> >
> > _________________________________________________
> > For list-related administrative tasks:
> > http://lists.racket-lang.org/listinfo/users

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20110405/d03f1c99/attachment.html>