Define Procedure or Function Parameters
Each parameter is immediately followed by a custom
<cc:param> element, in the SQL file in the left-hand image (see
Figure 3). The positioning is important for two reasons. First, if you later decide to change a parameter name or meaning, the corresponding documentation comment is right there, which makes it much more likely that you will also remember to update that as well.
 | |
| Figure 3. Automatic Parameter Documentation: You describe the parameter in your source SQL file, and then sqldoc2xml interprets your source code to insert the parameter details while XmlTransform converts sqldoc2xml's XML output into finished XHTML. |
Second, when the XML elements are properly interleaved with the parameters, the documentation tool saves you some initial work and some ongoing maintenance. This is the one case where the
sqldoc2xml tool looks not just at the comments but at the code as well; it parses the parameter names, types, and default values, and attaches those attributes to the XML element, as shown in the middle image in
Figure 3. Notice that the final HTML in the third image in
Figure 3 is a combination of the documentation comments and the actual SQL code.
I use
<cc:param> for my parameters, but you may use any name—sqldoc2xml attaches attributes by looking at the position of the XML element following the SQL parameter definition, not by its name. It is the second-stage tool—XmlTransform, which actually converts the XML to XHTML—that requires you to identify the XML element semantics and how those map to XHTML.
The custom
<cc:param> XML element gets mapped back to XHTML with an XSLT transformation, which renders it as a simple definition list (
<dl>...</dl>). The rule that creates the XHTML rendering shown in
Figure 3 includes a variety of formatting elements (bold, italic, colors, and indents) and even fills in the phrase "-none-" if the SQL code doesn't define a default value. You may, of course, choose to use something simpler or something more complex. Unlike all the other XML elements discussed here you do not need to fill in any attributes for the
<cc:param> element;
sqldoc2xml fills those in automatically, as shown in
Figure 3 and in Table 2.
Table 2: The <cc:param> Element: Use this macro tag to provide a description of each parameter to a procedure or function.
| XML element |
<cc:param>
parameter-description
</cc:param> |
| XML schema representation |
 |
| XSLT rule |
<xsl:template match="cc:param">
<dl>
<dt><xsl:value-of select="@name"/>
<span style="font-style:italic">
[
Type: <span style="color:green">
<xsl:value-of select="@type"/>
</span>
Default: <span style="color:green">
<xsl:choose>
<xsl:when test=
"string-length(@default)">
<xsl:value-of select="@default"/>
</xsl:when>
<xsl:otherwise>-none-
</xsl:otherwise>
</xsl:choose>
</span>
]
</span>
</dt>
<dd><xsl:apply-templates /></dd>
</dl>
</xsl:template> |
| SQL input sample |
@Description nvarchar(2048) = null,
—<cc:param>
—This parameter specifies blah, blah, blah, and blah.
—</cc:param> |
| Intermediate XML sample |
<cc:param
name="@Description"
type="nvarchar(2048)"
default="null">
This parameter specifies blah, blah, blah, and blah.
</cc:param> |
XHTML output sample
(see Figure 2, frame 2) |
<dl>
<dt>@Description
<span style="font-style:italic">
[ Type: <span style="color:green">nvarchar(2048)
Default: <span style="color:green">null ]
</span>
</dt>
<dd>
This parameter specifies blah, blah, blah, and blah.
</dd>
</dl> |
Display a Usage Block
This element provides a compact description of usage, a synopsis, specifying the syntax for a given procedure or function, a convention used for years on Unix/Linux manual pages. The XSLT rule for this element uses the HTML
<pre> element, which renders output in a fixed-width font, so it looks like a code sample. Additionally, the rule specifies a CSS style name to apply.
| Author's Note: There is significant overlap between what you can do with XSLT transformations and what you can do with CSS style applications. Often a combination of both is most efficient for producing a particular visual effect. See the <cc:product-summary> discussion for a more complex example of XSLT and CSS together. |
Table 3: The <cc:usage> Element: This macro provides a place to specify syntax or a synopsis for a procedure or function.
| XML element |
<cc:usage>
usage-text
</cc:usage> |
| XML schema representation |
 |
| XSLT rule |
<xsl:template match="cc:usage">
<pre class="codeBlock">
<xsl:apply-templates />
</pre>
</xsl:template> |
| SQL input sample |
— <cc:usage>
— MyProc @Description, @Verbose
— where:
— @Description ::= [string]
— @Verbose ::= [smallint] in the range 0 to 3
— <cc:usage> |
| Intermediate XML sample |
<cc:usage>
MyProc @Description, @Verbose
where:
@Description ::= [string]
@Verbose ::= [smallint] in the range 0 to 3
<cc:usage> |
XHTML output sample
(see Figure 2, frame 3) |
<pre class="codeBlock">
MyProc @Description, @Verbose
where:
@Description ::= [string]
@Verbose ::= [smallint] in the range 0 to 3
</pre> |
Previous Page
