Professional Visual Studio® 2008

Chapter 9. Documentation Using Comments and Sandcastle

Documentation is a critical, and often overlooked, feature of the development process. Without documentation, other programmers, code reviewers, and management have a more difficult time analyzing the purpose and implementation of code. You can even have problems with your own code once it becomes complex, and having good internal documentation can aid in the development process.

XML comments are a way of providing that internal documentation for your code without having to go through the process of manually creating and maintaining documents. Instead, as you write your code, you include metadata at the top of every definition to explain the intent of your code. Once the information has been included in your code, it can be consumed by Visual Studio to provide Object Browser and IntelliSense information.

Sandcastle is a set of tools that act as documentation compilers. These tools can be used to easily create very professional-looking external documentation in Microsoft-compiled HTML help (.CHM) or Microsoft Help 2 (.HxS) format from the XML comments you have added to your code.