Tuesday, June 3, 2014

Generating Help Documentation from XML Comments in .Net

Everyone seems to agree that using XML comments/documentation in code is the best way to keep code documents maintainable.

I've been working on a project, diligently filling in XML documentation on the public classes and methods in our API.  I knew I'd read plenty of articles on the web that described how documentation should be in one place and how a tool should be used to help generate documentation from the code base.  However, I had not dug into the actual implementation surrounding how to accomplish this utopia in a project.

After a few searches, the following became evident.
  • There is not a tool from Microsoft to transform the XML documents from code into something useful like a help file or website. 
  • However...
    • Microsoft used to have one called Sandcastle, development stopped a few years back.  
    • Development continues as an open source project called Sandcastle Help File Builder
      • Sandcastle Help File Builder provides
        • VS integration.
        • Command line
        • GUI
  • Doxygen is a great option for several languages, including C#
    • Doxygen can technically be used with VB.Net, but currently the links to any working scripts to get that functioning seem to be broken.
    • Doxygen provides
      • Command line
      • GUI
With that information, I was able to make an informed decision as to what tool I'd use on my current project. I ended up going with Sandcastle.  Like most new things, it takes some getting used to.  The documentation for how to use Sandcastle Help File Builder is top notch, so I won't go into detail.  The integration with Visual Studio is great, as it makes all the configuration feel somewhat familiar.  If you're looking for a documentation tool for your project, I'd recommend checking it out.

General XML Comment References:
MSDN Magazine June 2002
MSDN Magaize May 2009
C# Programming Guide
XML Comment Cheat Sheet

No comments:

Post a Comment