What's Missing?
At this point, it might be easy to say that VBCommenter is a perfect tool with everything you need to combine class or application comments with your documentation efforts. But the reality is that VBCommenter does a little over half the job. Yes, it creates the XML file you need, and that XML file is compatible with C#. Because of the high level of compatibility, VBCommenter makes your comments accessible to anyone who uses the class or application through the Object Browser and IntelliSense. However, that's not the end of the story: Most developers want some form of written documentation.
The VBCommenter author is honest and straightforward about this limitation. The developer suggests that you use either Custom Help Builder or NDoc with VBCommenter. These two utilities help you create physical documentation from the VBCommenter output. Custom Help Builder is another PowerToy, available in a 1.0 version. NDoc is a little more refined. At the time of this writing, the developer has released version 1.2, and the 1.3 version is available for testing. Because NDoc is a little more ready for prime time, the paragraphs that follow provide a quick overview of it.
NDoc helps you create MSDN-style documentation from the VBCommenter output. After you download and install the product, start NDoc. You'll see a dialog box similar to the one shown in Figure 4 (I've already configured this dialog box for use).
)
Figure
4 Define parameters in NDoc to compile a help file.
The fastest way to generate a help file in NDoc is to begin by choosing the assemblies you want to document. Simply click Add and follow the prompts. NDoc automatically retrieves the VBCommenter XML file associated with the assembly. Once you select the assembly, change properties such as the copyright notice for the help file. At a minimum, modify the OutputDirectory property (so you know where the help file will end up on disk) and set the ShowVisualBasic property to true (or else you won't get Visual Basic syntax in the help file). Click Build Documentation and NDoc goes to work. The results look impressive. I didn't do anything special with VBCommenter or NDoc to produce the output shown in Figure 5.
)
Figure
5 NDoc creates impressive results from the output generated by
VBCommenter.
The documentation is every bit as good as the documentation for class libraries that come with the .NET Framework. The difference is that these are your custom classes—the ones you designed. Getting professional results like this is definitely worth a few extra moments of typing while developing a class, and just one extra generation step.