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 2

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.

Getting From XML to MSDN-style Documentation
With the basic theory and the tags you'll need under your belt, you can now explore the tools to produce professional-looking documentation from your C# source code. As an example, Listing 1 shows a simple class documented with the XML tags shown in Table 1.

You can see that the XML tags reside within the triple-slash (///) comment blocks. Note that if you're using Visual Studio .NET, as soon as you type /// in front of a method or type, IntelliSense inserts the appropriate tags—well, really the most common. For example, here's what IntelliSense inserts when you type a triple-slash in front of the MyMethod method:

   /// <summary>
   /// </summary>
   /// <param name="str"></param>
   /// <returns></returns>
Note that Visual Studio inserts only the minimal XML tags needed to document the method. That is, you should provide at least a description of the method (inside the tag), a description of the method parameter (inside the tag) and what the method returns (inside the tag). Of course, you're free to insert other XML tags, such as <code>, <exception>, and so on. In fact, as Listing 1 shows, you can add other XML tags to enrich the resulting documentation.

That completes step 1 of the three main steps. The next step is to extract the XML comments to a file. If you're using Visual Studio .NET, there's an automated way to extract the XML comments to a file. First, create a new Console Application project, using the code in Listing 1 as the project's main class. To extract the XML tags to a file, follow these steps:

  1. Right click on the project in Solution Explorer and select Properties.
  2. Click on Configuration Properties and then select Build.
    Figure 2. Extracting XML Documentation: In Visual Studio, extracting XML comments requires only a few clicks and a file name entry.
  4. Enter a name in the XML Documentation File field and click OK.
  5. Build the project by clicking on Build and selecting Build Solution.
Figure 2 shows the process, using the name DevXDocumentation.xml for the file.

Notice that, by default, Visual Studio will save the XML file in the same folder as the assembly file created when you built the solution. In other words, if you accept the defaults, you'll find both the assembly and the XML file in the bin\Debug\ directory of your project. Listing 2 shows the extracted XML file.

In Listing 2, you can see that VS .NET adds some tags and structure when it extracts the XML. Although you don't really need to care about VS .NET's additions to produce your professional documentation, it's not difficult to figure out what they mean. For example, in the attribute name of the element in Listing 2, M: stands for method and T: for type. If you're curious about the formatting details, you can refer to this XML Documentation Tutorial for further information.

Close Icon
Thanks for your registration, follow us on our social networks to keep up-to-date