Define a Main Section
The
<cc:apiSection> element is a top-level container in which you would typically put most of the rest of your documentation. For example, the
downloadable sample files generally contain a preamble or introduction, and then you'll find several sections delineated with the
<cc:apiSection> element: Details, Usage and Parameters, and Examples. Table 6 shows the details.
Table 6: The <cc:apiSection> Element: This top-level container lets you render clearly delineated sections in the output.
| XML element |
<cc:apiSection name="section-name">
section-text
</cc:apiSection> |
| XML schema representation |
 |
| XSLT rule |
<xsl:template match="cc:apiSection">
<xsl:call-template name="spacerDiv"/>
<br />
<h2><xsl:value-of select="@name"/></h2>
<div style="margin-left:2em">
<xsl:apply-templates />
</div>
</xsl:template> |
| SQL input sample |
— <cc:apiSection name="Details">
— <p>
— This function provides a configurable, flexible interface to blah, blah, blah.
— </p>
— <p>Blah</p>
— <p>Blah</p>
— </cc:apiSection> |
| Intermediate XML sample |
<cc:apiSection name="Details">
<p>
This function provides a configurable, flexible interface to blah, blah, blah.
</p>
<p>Blah</p>
<p>Blah</p>
</cc:apiSection> |
XHTML output sample
(see Figure 2, frame 6) |
<div class="spacer"></div>
<br />
<h2>Details</h2>
<div style="margin-left:2em">
<p>
This function provides a configurable,
flexible interface to blah, blah, blah.
</p>
<p>Blah</p>
<p>Blah</p>
</div> |
Nutshell or Product Summary
This nutshell summary usually appears at the beginning of each documentation page to allow readers to grasp the salient points of the page in a few seconds. The top container is the
<cc:product-summary> element, which has no attributes—just contents. The contents consists of a series of
<cc:product-item> or
<cc:product-reference> children. For SQL pages, the examples use
Module,
Description,
Environment,
Author, and
Since, as shown in Table 7. The XSLT elements provide a way to distill the information for the nutshell summary, but all they give you is an XHTML table. It is the CSS "nutshell" class wrapping the table that renders the sleek, professional nutshell box on the final web page.
Table 7: The <cc:product-summary> Element: This top-level element holds a series of child elements containing common header-area information such as Author, Module, and Description.
| XML element |
<cc:product-summary>
<!— repeat as many cc:product-items as needed —>
<cc:product-item name="item-name">
item-text
</cc:product-item>
</cc:product-summary> |
| XML schema representation |
See full-size image |
| XSLT rule |
<xsl:template match="cc:product-summary">
<div class="nutshell">
<table cellspacing="0">
<tr><td colspan="2" class="nutshell-title">
N U T S H E L L</td></tr>
<xsl:apply-templates />
</table>
</div>
</xsl:template>
<xsl:template match="cc:product-item">
<tr>
<th><xsl:value-of select="@name"/></th>
<td><xsl:apply-templates /></td>
</tr>
</xsl:template>
<xsl:template match="cc:product-references">
<tr>
<th><xsl:value-of select="@name"/></th>
<td><xsl:apply-templates /></td>
</tr>
</xsl:template>
<xsl:template match="cc:product-reference">
<a class="btn" href="{@href}">
<xsl:apply-templates /></a>
</xsl:template> |
| SQL input sample |
— <cc:product-summary>
— <cc:product-item name="Module">
SP_map</cc:product-item>
— <cc:product-item name="Description">
— Maps a list or a matrix to an arbitrary
— DML statement</cc:product-item>
— <cc:product-item name="Environment">
— SQL Server 2000/2005</cc:product-item>
— <cc:product-item name="Author">
— Michael Sorens</cc:product-item>
— <cc:product-item name="Since">
— CleanCode 0.9.17</cc:product-item>
— </cc:product-summary> |
| Intermediate XML sample |
<cc:product-summary>
<cc:product-item name="Module">
SP_map</cc:product-item>
<cc:product-item name="Description">
Maps a list or a matrix to an arbitrary
DML statement</cc:product-item>
<cc:product-item name="Environment">
SQL Server 2000/2005</cc:product-item>
<cc:product-item name="Author">
Michael Sorens</cc:product-item>
<cc:product-item name="Since">
CleanCode 0.9.17</cc:product-item>
</cc:product-summary> |
XHTML output sample
(see Figure 2, frame 7) |
<div class="nutshell">
<table cellspacing="0">
<tr><td class="nutshell-title" colspan="2">
N U T S H E L L</td></tr>
<tr><th>Module</th><td>SP_map</td></tr>
<tr><th>Description</th>
<td>Maps a list or a matrix to
an arbitrary DML statement</td></tr>
<tr><th>Environment</th>
<td>SQL Server 2000/2005</td></tr>
<tr><th>Author</th>
<td>Michael Sorens</td></tr>
<tr><th>Since</th>
<td>CleanCode 0.9.17</td></tr>
</table>
</div> |
At this point, you've covered the key XML elements for instrumenting a SQL file with documentation comments. You'll find a few others in the XSLT file (
translate.xsl), most of which are documented
here.
Previous Page
