Open Source .NET Development [Electronic resources] نسخه متنی

Introduction

Have you ever received a component either from a vendor or another programmer in your organization, only to find out that the API documentation is out of date? If not, count yourself lucky, but it is just a matter of time. It is a fact of life that programmers do not like to write documentation, and as a result, sometimes the documentation does not match the functionality of a product. As I mentioned in Chapter 2, "Open Source and the .NET Platform," design documentation should be done in the design phase, not during the release. At the very least, the code should be well documented. Some argue that the best place for this documentation is inline with the code. Others say this unnecessarily clutters the code. This will be argued to the end of software development time almost as vehemently as use of tabs vs. spaces in code. The team should decide the best way to keep the documentation in sync with the code and enforce strict coherence. But no matter what the documentation, one thing everyone can agree on is that an XML format should be used in the documentation.

The Magical Documentation Tool in Figure 5-1 does in fact exist and it is called NDoc. There are many tools to create this nicely formatted user documentation, but NDoc offers the most functionality. But before going straight into what NDoc can do, some knowledge about the workings of the C# XML documentation and compiler is necessary. In addition, other documentation tools will be evaluated to help you determine which one is right for you.