Windows Developer Power Tools

7.3 Creating Professional Documentation with NDoc

API documentation for your software is critical. Your system needs to be well documented so that you can understand how it all fits together and how to correctly make calls to various pieces in order to get the expected results.

While this information is critical, you certainly don’t want to be manually creating this documentation in some Word file. Copying and pasting information from your classes’ XML documentation (you are writing that, aren’t you?) is a recipe for disaster as you refactor your code—you’re certain to have disconnects between that Word document and what’s in your final code.

How can you make use of those XML comments to generate professional, clear API documentation without worrying about versioning issues? Enter NDoc, a program that ties together your in-class XML comments with Microsoft’s HTML Help Workshop to produce great-looking documentation straight from your source code.

Tip

The dynamic nature of developer tools has impacted this article as well. Literally days before this chapter was sent off to production, the sole developer and administrator for the “official” version of NDoc announced he was leaving the project. NDoc’s future status is unclear, although some in the community appear to be interested in moving forward with the project.

Additionally, Microsoft has released a Community Technical Preview of Sandcastle, its attempt at creating an XML comment-to-documentation tool. Sandcastle’s CTP can be found ...