Visual Studio Hacks [Electronic resources] نسخه متنی

Hack 71. Create Documentation from XML Comments

Make all that typing and tagging pay off with
an open source documentation tool that creates help documents from
your XML comments.

So you have a large number of XML comments
peppered throughout your application. Now what can you do with them?
While Visual Studio includes some tools to work with these comments,
the real benefit comes from an open source tool called NDoc. NDoc is a tool that will take your
XML comments and turn them into a number of different types of
documentation, including help files or MSDN-style web documentation.

The first step to creating your documentation is to generate an XML
file with all of your XML comments. To do this, follow the
instructions in either [Hack #68]
if you are using C# or [Hack #70] if you are using
VB.NET.

Once you have the .xml file, you are ready to
turn it into full documentation.

8.5.1. Using NDoc

The next step is to download and install NDoc from http://ndoc.sourceforge.net. Once you have
downloaded and installed NDoc, you will need to open the application,
which is shown in Figure 8-4.

Figure 8-4. NDoc window

The next step is to create a new
NDoc Project. This can be done one of
two ways: you can create a new blank project and then manually select
each of the assemblies that you want to document, or you can select
New from Visual Studio Solution and select your solution, after which
NDoc will load all of your assemblies.

After loading your assemblies, you can then configure how you want
your documentation to be generated. There are way too many options to
cover here, but suffice it to say you can configure just about any
part of the documentation that you wish. The main choice is what type
of documentation you want to generate. This is controlled by the
Documentation Type drop-down. From this list you can choose any
number of different types (for this example, I will leave the option
set to the default, MSDN).

From this point, you simply need to click the Build button and NDoc
will generate the documentation based on your XML comments. Figure 8-5 shows an example of the help file generated by
NDoc.

Figure 8-5. Ndoc-generated help file

NDoc also generates web documentation, which can be seen in Figure 8-6.

Figure 8-6. Ndoc-generated web documentation

This tool is actually that simple. In just a couple clicks, you can
go from your XML comments to high-quality documentation. NDoc is a
complex application with a multitude of options and different
formats; I encourage you to explore the tool and its options. The
tool comes with good documentation (as it should!), and you can also
find lots of information at
the NDoc Wiki, located at http://ndoc.sourceforge.net/wiki.