Geeks With Blogs

News Google

Nick Harrison Blog<Nick>.Next()

Recently I blogged about adding SQL Doc Documentation to you Application.    This makes it easy to keep your documentation visible and more likely current.

I wanted to do the same thing with my code documentation.   I wanted to leverage the work taken to add XML comments and add even more visibility.


There are already tools readily available to convert these XML comments to MSDN looking documentation or help files, and these comments get incorporated into intellisense as you are writing code.

I did not want MSDN style documentation.   I wanted documentation that could be incorporated into the actual application and look like it flowed with everything else.   


When you build a project, you can specify the XML Documentation file.   All of your XML Comments will be added to this file:


Since this is XML, getting the output to look the way that I want seems like a perfect problem for XSLT to solve.

A little Google searching, brought me to this page on Code Project.   Here Emma Burrows provides a base template formatting this XML.

Out of the box, we have a vanilla set of documentation.    Not bad, but not fancy, and it does not look like it flows with the rest of the application.   We have a blank slate ready to style:



For the most part, all  we really have to do is style the output.   In some cases, I added classes to the template to simplify matters.

I created the following classes:

  • typeName  to Style the Types
  • summary to give consistent formatting to the summary sections in the documentation
  • memberType to separate the different member types such as properties, methods, events, etc
  • memberName to separate the individual members


Adding the class to the template is straightforward.   You just find where the corresponding element is being created.   Emma has already done most of the heavy lifting for us.

So this code:

   1:    <!-- Display the type's name and information -->
   2:    <H2><xsl:value-of select="$MemberName"/></H2>
   3:    <xsl:apply-templates/>

become this:

   1:    <!-- Display the type's name and information -->
   2:    <H2 class ="typeName"><xsl:value-of select="$MemberName"/></H2>
   3:    <xsl:apply-templates/>


Also if you wanted to change the tags being used, this is also a fairly trivial change as well.

In honesty, the tags that Emma uses work well.   You don’t actually have to add the classes, but it does make it easier to style.

Inside your application, there are a couple of things you will need to do to wire all of this together:

Fist, add an extension method similar to Jigar Desia's RenderXML.   This method makes it easy to associate an XmlDocument and an XSLT template.

Mine looks like this:

   1:  public static void RenderXML<T>(this  ViewPage<T> page, 
   2:      XmlDocument xmlDocument, string xsltPath,
   3:      Dictionary<string, string> xslArgParams)
   4:  {
   5:      var context = page.Html.ViewContext;
   6:      var xslArgs = new XsltArgumentList();
   7:      if (xslArgParams != null)
   8:      {
   9:          foreach (string key in xslArgParams.Keys)
  10:          {
  11:              xslArgs.AddParam(key, null, xslArgParams[key]);
  12:          }
  13:      }
  14:      var t = new XslCompiledTransform();
  15:      t.Load(xsltPath);
  16:      t.Transform(xmlDocument, xslArgs,
  17:                  context.HttpContext.Response.Output);
  18:  }


Next I defined a CodeDocumnentationViewModel

public class CodeDocumentationViewModel
    public XmlDocument Code { get; set; }
    public IList<string> AvailableFiles { get; set; }

This will provide an XmlDocument for the file currently selected as well as list of all available XML files

Inside the View, this is all we need to do display the formatted documentation:

   1:  <%
   2:      if (Model.Code != null)
   3:      {
   4:  %>
   5:          <div class = "codeComments">
   6:          <%
   7:          this.RenderXML(Model.Code,
   8:                         Server.MapPath("/Documentation/CodeComments/documentation.xsl"), null);
   9:  %>
  10:          </div>
  11:          <%
  12:      }
  13:      else
  14:      {
  15:    %>
  16:      <img src="../../Content/images/CodeComments.png" />
  17:    <%
  18:      }
  19:    %>
If we don’t have a valid XmlDocument, we will simply display a place holder picture, otherwise, we will call the RenderXML.
The other thing left to do is to add a display listing out the available files.
   1:  <h1 class="ui-widget-header">Available Files</h1>
   2:  <ul class = "ui-widget">
   3:  <% foreach (var file in Model.AvailableFiles  )
   4:  {
   5:    %>
   6:    <li class ="ui-state-default"><%= Html.ActionLink(file, "ShowCode", new {fileName= file}) %> </li>
   7:    <%
   8:  } %>
   9:  </ul>
  10:  </div>

In the end, I think that the format looks pretty good.   What do you think?


Posted on Friday, March 1, 2013 12:07 PM Documentation | Back to top

Comments on this post: Exporting XML Comments to Your Application

comments powered by Disqus

Copyright © Nick Harrison | Powered by: