NAME

sqldoc2xml - Separate doc-comments in an SQL file to a separate XML file.

SYNOPSIS

sqldoc2xml [ -lhH ] dirs target-directory

OPTIONS

-h: Option help.
-H: Long help (manual page).
-l: List actions but do not make any changes (simulation).

REQUIRES

Perl5.005, File::Find, File::Copy, Cwd, Getopt::Std, Pod::Usage, Data::Handy, File::Handy

DESCRIPTION

Extracts XML documentation comments from SQL files (*.sql) in preparation for using XmlTransform. The extracted XML from the specified SQL source tree is written to the destination directory in a comparable tree. Additionally, any contents files (_index.xml) in the source tree are copied without modification to the destination tree. The destination tree may then be used as input to the Java tool XmlTransform (http://cleancode.sourceforge.net/api/java/com/cleancode/xml/XmlTransform.html) with appropriate options to spawn a second-generation HTML destination tree.

sqldoc2xml recognizes the start of am embedded documentation section by the presence of a comment marker (--) followed by an opening bracket for an XML tag (<). Whitespace between tokens is ignored. All subsequent, contiguous lines which have comment markers are also considered to be part of the embedded documentation set. Once a non-comment line is encountered, all text is ignored until the comment marker and XML opening bracket are again found on a single line. This lets you conveniently interleave your documentation comments with your code.

sqldoc2xml also has the capability to automatically generate attributes detailing your parameter names, types, and default values. These attributes are attached to the first subsequent opening XML tag that is encountered. The region of code between the CREATE and the BEGIN statements is scanned and attributes are collected for each parameter encountered. You just need to make sure you have an XML element right below the parameter to accept the attributes. In the sample below, attributes about the @list parameter will be added to its following <param> tag, and similarly for the @delimiter parameter.

    CREATE PROCEDURE [dbo].[SP_myProc]
    (
        @list VARCHAR(100),
    -- <param>
    -- A string containing a list of items separated by the
    -- specified @delimiter.
    -- </param>
    
        @delimiter CHAR(1) = ','
    -- <param>
    -- A character used between each pair of items in the @list.
    -- </param>
    )
    
    AS
    BEGIN

The resulting XML for the above fragment will be:

    <param name="@list" type="VARCHAR(100)" default="">
    A string containing a list of items separated by the
    specified @delimiter.
    </param>
    <param name="@delimiter" type="CHAR(1)" default="','">
    A character used between each pair of items in the @list.
    </param>

With release 1.1.02, you can now also document parameters to scripts (i.e. those variables that are appropriate for the user to tweak to get desired behavior). Declare each variable separately, and put a line break between the DECLARE keyword and the subsequent declaration, e.g.:

    DECLARE
    @Filter nvarchar(255) = null

The DECLARE keyword signals the processor to extract the details of the following declaration (just as the CREATE keyword did for stored procs), and the subsequent apiSection signals the end of the region. (See the CleanCode SQL ValidateStoredProcs script for an example.)

Examples

Copy from the current directory into a sub-directory contained within it:

        sqldoc2xml.pl . doc

Copy from one subdirectory to another:

        sqldoc2xml.pl src XMLsrc

Copy several subdirectories to a target:

        sqldoc2xml.pl src1 src2 src3 targetDir

EXIT STATUS

Return Code 0: Normal exit.
Return Code 1: Target is not an existing directory.

BUGS

None

AUTHOR

Michael Sorens

VERSION

$Revision: 1177 $ $Date: 2011-10-31 14:26:04 -0700 (Mon, 31 Oct 2011) $

SINCE

CleanCode 0.9.17

CleanCode Perl Libraries