Login | Register   
RSS Feed
Download our iPhone app
Browse DevX
Sign up for e-mail newsletters from DevX


Producing Professional MSDN-style Documentation with .NET and NDoc : Page 3

Tired of trying to keep your documentation synchronized with the source? You can help alleviate the problem by creating professional documentation directly from the built-in XML documentation features of the C# language using the brilliant NDoc open-source application.

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 document—the 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 like—I 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 and FeedbackEmailAddress; 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 step—inserting the tags you want before any member using triple-slash code blocks—with any text editor. The second step—extracting the corresponding XML file—is 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 MyClass.cs

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 tools—and NDoc is one of them—supply "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.

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.
Integrating with .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.

Alessandro Lacava is a software developer and technical writer based in Italy. He is mainly interested in Java and .NET technologies, Web applications and telecommunication systems. Alessandro holds a degree in telecommunications engineering. You can reach him via his Web site.
Comment and Contribute






(Maximum characters: 1200). You have 1200 characters left.