Using NDoc to Create Documentation
Now that you have the XML file and the assembly file, you can use NDoc to produce the professional MSDN-style documentation you saw in Figure 1
. Figure 3
shows the NDoc interface.
|Figure 3. NDoc GUI: This is NDoc's main user interface, showing a partial list of the properties available to tune the output to your needs.|
As Figure 3
shows, you can set many options that can affect the final form of the documentation. However, for simplicity's sake, I'm going to set only a couple of them. Nevertheless they will be enough to produce the documentation file shown in Figure 1
. You can explore the other options thoroughly by clicking on each of them and reading the "on-the-fly" help at the bottom of the GUI. For example, at the bottom of Figure 3
you can see the related help for the OutputTarget option.
|Figure 4. Assembly and XML file selection: When you select your project assembly, NDoc automatically selects the associated XML comments file if it resides in the same directory.|
To create the documentation file, click on the Add button and select the assembly you want to documentthe assembly in the bin\Debug\
directory of your project. As soon as you select the assembly, NDoc automatically finds the XML file associated with it, because they're in the same folder (see Figure 4
). Click OK to confirm.
Now you can set a couple of NDoc properties. The first one is the OutputTarget
under Documentation Main Settings (see Figure 3
). Select HTML Help as the OutputTarget
. This property causes NDoc to produce a .chm
file like that shown in Figure 1
. The second is the OutputDirectory
property, which specifies the output directory in which NDoc stores the documentation file. For this example, create a folder under your bin\Debug\
directory and name it whatever you likeI named it Doc
. To select the folder you've just created, select OutputDirectory in the Documentation Main Settings and browse to the directory you created. Finally, select Build
Documentation to create the documentation (see Figure 5
|Figure 5. Building the documentation with NDoc: After setting the output properties, building the documentation is as simple as selecting "Build" from the Documentation menu.|
That's it! If everything worked you will have created your first NDoc professional documentation file (a .chm
file) in the bin\Debug\Doc\
folder (along with other support files generated by NDoc). The .chm
file should look similar to Figure 1
Explore Other NDoc Options
Now that you have the basics working, I urge you to research and explore the other options available. For example, two interesting options are SdkDocLanguage
; you'll find both under the Documentation Main Settings. SdkDocLanguage
lets you specify the .NET Framework SDK language displayed when users click on links to system types. FeedbackEmailAddress
inserts a mailto
link at the bottom of each page that points to the e-mail address supplied; that's useful if you want to receive feedback about your code.
Using NDoc Without Visual Studio .NET
Although at this point you've seen enough to create well-formatted documentation using NDoc, there are a few other points to cover. First, while this article described the process of using NDoc with VS .NET, it's extremely easy to use NDoc even if you don't have VS .NET installed on your machine. You can accomplish the first stepinserting the tags you want before any member using triple-slash code blockswith any text editor. The second stepextracting the corresponding XML fileis almost as simple: You just use the /doc
switch with the csc.exe
command-line compiler. For example:
|Figure 6. Web Documentation: The figure shows an example of the Web (HTML-formatted) documentation you can produce with NDoc.|
csc /out:DevXDocumentation.exe /doc:DevXDocumentation.xml
From that point you can proceed with NDoc just as described in this article.
Using Custom Tags
Another thing to know is that you aren't limited to using the standard XML tags supported by Visual Studio .NET. Some toolsand NDoc is one of themsupply "proprietary" tags to enrich your documentation. See the NDoc project page
for further details.
Extending Documentation Types
Another interesting feature is that you can produce Web documentation as well as help files by selecting Web
as the OutputTarget
in the Documentation Main Settings section. When you build the output as Web documentation, you can double click on the generated index.html
file to view the content. Figure 6
shows an example of the Web documentation output.
Integrating with .NET Documentation
|Figure 7. Integrated Documentation: Clicking on the String link in the NDoc-generated documentation file brings up the System.String page of the .NET documentation.|
Last but not least, notice that if you installed the MSDN help files while installing Visual Studio .NET, your custom documentation will be integrated with the Visual Studio .NET documentation. For example, if you click on the String
link in the documentation file you created you will get the "native" documentation for the System.String type of the .NET Framework (see Figure 7
NDoc takes much of the pain out of generating documentation. By leveraging the .NET native support for XML documentation, NDoc can create either professional-quality MSDN-style help files integrated with Visual Studio .NET help or nicely-formatted Web pages with equal aplomb.