Codedoc

Have you ever wished there was a tool that could automatically create documentation for your SAS® 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, the 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. The best way to see how this works is by example. Here's a very short SAS macro with a codedoc header comment. Codedoc is not limited to macro programming, but this is a good place to start:

/* ----------------------------------------------------------------
 * 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...
 * ---------------------------------------------------------------- */

%macro macro1(DEPT=,SUMMARY=Y);
    /* do something here */
%mend macro1;

Codedoc builds an XML document containing the information in your codedoc header comments. If the above file is the only source file that codedoc reads, the XML will be:

<?xml version='1.0'?>
<code>
    <file>
        <name>macro1.sas</name>
        <purpose>Performs some function as a macro.</purpose>
        <param>DEPT - Department name (required)</param>
        <param>SUMMARY - Y/N flag to control whether this macro 
         performs a summary function.  Defaults to Y.</param>
        <return>none</return>
    </file>
</code>

This XML can also be associated with an XSL stylesheet, so that it can be viewed in a friendly way in a web browser:

Codedoc is available now for free CodeDoc (Zip file)(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.