And Then There's the Documenter

The Documenter seems like a good idea until you really begin using it.

Creating a documentation file isn't hard: simply right click the assembly you want to document and choose either Documenter | Create NRDOC for Selected Assembly or Documenter | Create NRDOC for Entire Project from the context menu. The application asks where to save the document. After you save the document, the program asks whether you want to load the resulting document. Unfortunately, this process always fails with an error message. Fortunately, you can load the file manually to view it.

Woes using the Documenter don't stop with a less than convenient and error-prone generation method. The resulting NRDOC isn't compatible with Visual Studio, so the documentation you generated is worthless to you as a developer. After you add your comments to the NRDOC, you must perform the second step of using the Tools | Documenter | Export to Xml Documentation command to export the file in a usable form.

And the problems just keep going. The first time you create an NRDOC file, you'll notice that it doesn't include any comments you provide in your code. For example, the product completely ignores the /// syntax used by C# and the ''' syntax used by Visual Basic to generate comments.

I talked with a company representative about this problem. Supposedly, generating an XML file when you build the application will resolve this issue, but I never got the fix to work. And ,of course, having the generate the XML file from Visual Studio begs the question of why you need Documenter in the first place.

Consequently, anything you type into your code is gone; you have to generate it again, or use the built-in functionality that Visual Studio provides.

In addition, the software doesn't even catch everything you need to document. During my tests, I noticed that it seemed to generate entries for the form, but not for the Button1 event handler. As program complexity increases, Documenter appears to miss more essential entries.

Once you create your comments and generate an XML file that you can actually use, you don't have any way to getting the comments back into your source file. Therefore, even though you'll see the comments you've created for the executable in the Object Browser, they're not available for inclusion in your application code.

The only use I can see for this feature is to create comments for someone else's code, which is something you normally won't need to do. In short, this part of the suite isn't particularly useful and I would recommend against using it in most cases.