Date:         Fri, 20 Jul 2007 08:32:24 -0400
Reply-To:     Jeff Wright <jwright@THOTWAVE.COM>
Sender:       "SAS(r) Discussion" <SAS-L@LISTSERV.UGA.EDU>
From:         Jeff Wright <jwright@THOTWAVE.COM>
Subject:      free tool announcement: codedoc
Content-Type: text/plain; charset=us-ascii

Have you ever wished there was a tool that could automatically create 

documentation for your SAS(r) source code? 

 

Perhaps you've seen how the javadoc tool turns structured header
comments inside 

Java source into HTML API documentation, and wished for something
similar for 

SAS. 

 

If so, codedoc may be the tool for you. Codedoc is able to read a
directory of 

SAS code source files and extract documentation from header comments
that follow 

simple formatting conventions.  Here's an example of a codedoc header:

 

    /* ----------------------------------------------------------------

     * codedoc will start paying attention after the next line...

     * <doc>

     * @purpose Performs some function as a macro.

     * @param DEPT - Department name (required)

     * @param SUMMARY - Y/N flag to control whether this macro 

     *  performs a summary function.  Defaults to Y.

     * @return none

     * </doc>

     * codedoc will ignore the remainder of this file...

     * ----------------------------------------------------------------
*/

 

Codedoc is available now for free download (registration required) under
the 

Eclipse Public License. The distribution includes the codedoc.pl perl
script and 

a sample XSL style sheet for formatting extracted documentation as HTML.


 

For more information or to download, please visit:

  http://www.thotwave.com/products/codedoc.jsp  

 

There is also a page at sascommunity.org: 

 
http://www.sascommunity.org/wiki/Codedoc_-_Automated_Documentation_Tool

(currently it has no more info than this announcement)

 

Thanks to the sasCommunity web site, I've already learned from Alan
Churchill

that he has created a similar tool called SaviDoc:

  http://www.sascommunity.org/wiki/SaviDoc

  

Alan's tool seems to use a slightly different, more HTML-ish format for 

the header, and to directly generate HTML.  Codedoc is written in perl,
which 

makes it inherently cross-platform and amenable to batch operation.
However,

I've been wondering if codedoc leaves too much burden to the user to
create

his or her own formatted output.  There tends to be a tradeoff between 

flexibility and doing something useful out of the box.

 

Looking forward to your feedback...

 

--Jeff Wright

  ThotWave Technologies