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

From: Eduardo Bellani (ebellani at gmail.com)
Date: Tue Apr 5 17:14:59 EDT 2011

There is also http://www.cs.aau.dk/~normark/schemedoc/

On 04/05/2011 05:44 PM, Charles Hixson wrote:
> 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
> _________________________________________________
>   For list-related administrative tasks:
>   http://lists.racket-lang.org/listinfo/users

Eduardo Bellani

omnia mutantur, nihil interit.

Posted on the users mailing list.