ToolKit
LANGUAGES: C#
TECHNOLOGIES: Code-Behind | XML | XSLT | HTML Help
Document Your Apps
NDoc makes it easy to create MSDN-style documentation for your ASP.NET projects.
By Ken McNamee
Professional-quality documentation has never been easier. If you're using C# to build your ASP.NET applications already and are decorating your class members with XML comments (see References), you're only a few clicks away from documentation that looks and functions much like the HTML Help included with Microsoft's .NET Framework and Visual Studio .NET. What makes this possible is NDoc (see References) - an open-source, third-party tool that provides a great deal of functionality.
You need only three things to get started with NDoc: the .NET Framework, HTML Help, and the NDoc source code you will need to be compiled. Now don't get stressed - we're not recompiling the Linux kernel here. NDoc comes with Visual Studio .NET solution and project files, so all you have to do is open the solution file and click on Build. But if you don't have a copy of Visual Studio .NET, you're not out of luck. Also included is a makefile that requires only the .NET Framework.
Because NDoc is so easy to download and build, you have no excuse for not trying it, right? Well, there might be one valid excuse. It's only fair to mention that NDoc is useless unless you're coding in C#. XML documentation is not, at this time, supported in VB .NET or any of the other Common Language Specification-compliant languages, and this reason is one of the many why C# continues to be my language of choice for developing .NET applications.
Prepare Your Code
In addition to writing your code in C#, your class members must be prefixed by XML documentation sections. This code listing demonstrates what that would look like:
///
/// Represents one table of in-memory data.
///
public class DataTable
\\{
///
/// Computes the given expression on the current rows
/// that pass the filter criteria.
///
/// The expression to
/// compute.
/// The filter to limit the
/// rows that evaluate in the expression.
///
/// computation.
public object Compute(string expression, string filter)
\\{
return true;
\\}
\\}
When this code is compiled, the C# compiler strips out the special XML documentation comments and merges them into a single XML file per project. Neither Visual Studio .NET nor the C# compiler, however, will do this for you automatically. You must pass the compiler the /doc switch and the filename of the merged XML file for this process to occur. In Visual Studio .NET, you accomplish by opening the Project Properties dialog and navigating to the Build section of the Configuration Properties. Then you simply need to fill in the XML Documentation File option and Visual Studio .NET will know to compile the project with the /doc switch. If you aren't using Visual Studio .NET and are instead directly invoking the C# compiler, this command demonstrates how to create the merged XML file:
C:>csc /target:library NDocEXample.cs /doc:NDocEXample.xml
Now that you have built both the assembly and its corresponding XML documentation file, you can fire up NDoc and let it do the rest of the work. Simply point NDoc at your Visual Studio .NET solution file and it determines which files to include in the compiled help. Or, you can add the assembly and XML file manually if you want more control or are not using a Visual Studio .NET solution. Additionally, you can set a number of properties to configure the resulting HTML Help, such as whether to display Visual Basic .NET syntax for the class members and whether to include private, protected, or internal members in addition to the public ones.
Once you've set all the NDoc options for your project, simply click on Build and navigate to the output folder for the HTML Help file. Open the \\[project name\\].chm file and explore the project classes and members. You should see something similar to Figure 1.
Figure 1. Look familiar? NDoc's finished product looks and functions much like the MSDN .NET documentation.
If you sell or distribute compiled class libraries for other developers to consume, NDoc can be a real timesaver when it comes to creating professional, high-quality documentation.Even if you create only internal assemblies for an Internet or intranet site, however, NDoc can still be an important part of your development toolbox. New developers on your team probably will find the learning curve a little less steep if they can reference your class members in a familiar format that integrates seamlessly with the .NET Framework Help.
There is much more to NDoc and XML documentation than I've mentioned here. So do yourself a favor and explore all the other options and tags available. You even can define your own tags and tweak the XSLT to render the Help file the way you want it. Who knows, it may be as close as you're going to get to (truthfully) claiming that your code is self-documenting!
References
NDoc: http://ndoc.sf.net
XML Docs: http://msdn.microsoft.com/msdnmag/issues/02/06/xmlc/xmlc.asp
Ken McNamee is a senior software engineer with RelayHealth Corp., the premier provider of secure, Web-based doctor-patient communication services. Prior to this, he led a team of developers in re-architecting the Home Shopping Network's e-commerce site, HSN.com, to 100 percent ASP.NET with C#. E-mail him at [email protected].
