Login | Register   
Twitter
RSS Feed
Download our iPhone app
TODAY'S HEADLINES  |   ARTICLE ARCHIVE  |   FORUMS  |   TIP BANK
Browse DevX
Sign up for e-mail newsletters from DevX


advertisement
 

Add Custom XML Documentation Capability To Your SQL Code : Page 5

By adding XML-based documentation capability to your SQL code, you can automatically extract and format tagged comments into a complete API documentation set for your SQL libraries.


advertisement
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.



Comment and Contribute

 

 

 

 

 


(Maximum characters: 1200). You have 1200 characters left.

 

 

Sitemap