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

From: Charles Hixson (charleshixsn at earthlink.net)
Date: Tue Apr 5 18:16:08 EDT 2011

Schemedoc looks interesting, but it specifically says that it won't work 
with R6RS scheme, and it doesn't list Racket as something it works 
with.  I guess that if it doesn't work, I can use another scheme to 
generate the documentation for the files though, even if they wouldn't 
work in that scheme.  (Or perhaps if I just set #lang R5RS it would work.)

On 04/05/2011 02:14 PM, Eduardo Bellani wrote:
> 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
>>      
>
>    



Posted on the users mailing list.