Professional Visual Studio 2012

Chapter 12

Documentation with XML Comments

WHAT’S IN THIS CHAPTER?

• Adding inline documentation to your code using XML comments
• Using the GhostDoc Visual Studio Add-In to automatically generate XML comments
• Producing standalone documentation from XML comments with Sandcastle
• Using Task List comments to keep track of pending coding tasks and other things to do

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

XML comments are a way to provide that internal documentation for your code without having to go through the process to manually create and maintain a separate document. Instead, as you write your code, you include meta data at the top of every definition to explain the intent of your code. When the information has been included in your code, it can be consumed by Visual Studio to provide Object Browser and IntelliSense information.

GhostDoc is a free third-party add-in for Visual Studio that can automatically insert an XML comment block for a class or member.

Sandcastle is a set of tools that act as a documentation compiler. You can use these tools to easily create standalone documentation in Microsoft compiled HTML help or Microsoft Help ...