Windows Developer Power Tools

7.0 Introduction

Software documentation comes in many flavors, ranging from design and specification documents to XML comments used to generate help files. Each type of documentation can morph into a black hole that sucks up useless hours and effort, but on the plus side, they each contribute some unique, beneficial value to your projects.

This chapter focuses on tools that help you document your software’s API: the classes, methods, and fields that you’ve created to build your system. Documentation offers something for everyone. Newcomers to a project trying to get an understanding of the system’s structure need something other than plain source code when trying to understand high-level interaction of components. Old hats on a project need pointers to quickly refresh their memories on how and why parts of the system act as they do.

Documentation can give you that boost by clearly laying out your API at the 30,000-foot level, while also giving you the ability to dive into details where needed. Start by writing simple, concise XML comments in your source code. For example, this snippet from the Genghis library shows a summary for a property describing what the property does and exactly what the input parameter is used for:

/// <summary> /// Use pull model to populate smart tag menu. /// Defines a list of items used to create /// a smart tag panel. /// </summary> /// <value>Represents a collection of DesignerActionList objects.</value> public override DesignerActionListCollection ActionLists ...