Documenting Revisions in XML Documentation Comments

XML Documentation Comments are a great feature within .NET (although credit does go to Sun with their JavaDoc which XML comments are based off).  One thing that is missing is the ability to document the revisions to a code construct (types and type members).  As a class library matures and gets changed to meet changed/new requirements, it helps to know when and what was changed.

For the longest time I have been my own <revisions> tag with <revision> tags within.  The revision tag contains the following parameters:

date
The date the revision to the code construct was made.

author
Name of the author that made the revision.

version
The version of the assembly where the revision was made.

cc
Identifier of the change control item.

Example
”’ <summary>
”’ Returns the <see cref="Boolean">Boolean</see> value of the specified column.
”’ </summary>
”’ <param name="input">The <see cref="DataRow">DataRow</see> containing the desired data.</param>
”’ <param name="columnName">Name of the column to retrieve the desired data from.</param>
”’ <returns>The <see cref="Boolean">Boolean</see> value stored in the specified column.</returns>
”’ <remarks>If the specified column contains a null, the return value will be <c>False</c>.</remarks>
”’ <revisions>
”’   <revision date="11/2/2008" author="Chad Green" version="1.00.00.000">Initial Development</revision>
”’ </revisions>
<Extension()> Public Function GetBooleanValue(ByVal input As DataRow, _
                                                                   ByVal columnName As String) As Boolean
  Return GetBooleanValue(input, columnName, False)
End Function

Documentation Generation
Once you start using this tag, you’ll need to update the main_sandcastle.xsl file to include the revision information in your documentation.  The location of this file will depend on the presentation style you’re using.  For example, if you the vs2005 style the file will be located at C:\Program Files (x86)\Sandcastle\Presentation\vs2005\transforms\.  First, you’ll need to add the following to the "body" xsl template:

Then, you’ll need to add the following xsl template:

<xsl:template match="revisions">
  <xsl:call-template name="section">
    <xsl:with-param name="toggleSwitch" select="‘revisons’"/>
    <xsl:with-param name="title">Revisions</xsl:with-param>
    <xsl:with-param name="content">
      <div class="tableSection">
        <table width="100%" cellspacing="2" cellpadding="5" frame="lhs">
          <tr>
            <th>Date</th>
            <th>Author</th>
             <th>Version</th>
             <th>Description</th>
           </tr>
           <xsl:for-each select="revision">
             <tr>
               <td>
                 <xsl:value-of select="@date" />
               </td>
               <td>
                 <xsl:value-of select="@author" />
               </td>
               <td>
                 <xsl:value-of select="@version" />
               </td>
               <td>
                 <xsl:apply-templates />
               </td>
             </tr>
           </xsl:for-each>
         </table>
       </div>
     </xsl:with-param>
   </xsl:call-template>
</xsl:template>

Now when you generate your documentation, you will have something like this added to your documentation: