devxlogo

Producing Professional MSDN-style Documentation with .NET and NDoc

Producing Professional MSDN-style Documentation with .NET and NDoc

Why Trust Us

he .NET framework provides a nice way to insert XML documentation tags inside C# source code. These tags can then be extracted to an XML file, and using NDoc, transformed into fully-functional MSDN-style documentation.

Software Needed
Before delving into the how the process works, here’s a short list of the software you need to run the samples for this article:

Author’s Note: If you have installed Visual Studio .NET you might already have the HTML Help Workshop installed on your machine. You can verify that by checking for the directory C:Program FilesHTML Help Workshop.

Installing NDoc is generally very smooth, so it doesn’t require any additional instructions.

?
Figure 1. MSDN-style documentation sample: This is the quality of documentation that you can get directly from the C# XML comments with NDoc.

If you don’t have Visual Studio .NET, don’t worry, at the end of this article I’ll describe how you can still use NDoc, provided that, of course, you have at least the .NET framework installed plus HTML Help Workshop and NDoc.

XML documentation tags in C#
The process of building MSDN-style documentation similar to Figure 1 can be summarized in three main steps:

  • Document your C# source code by using the XML documentation tags.
  • Extract the XML documentation tags to an XML file.
  • Tell NDoc where it can find the extracted XML file and the assembly associated with it?that is the .dll or .exe file.

Typically, you’ll use a rather short list of XML tags to document your C# source. The following table lists the most-used tags (in alphabetical order) with a short explanation and an example for each one:


Table 1: The table shows an alphabetical list of the most commonly used XML tags when documenting C# source code.

TagDescriptionExample
Used to differentiate the code font from the normal text font.
The Foo class provides...
Similar to but used to demarcate multiple lines of code. Usually used to show a code usage example.
 
   // create an instance of the Foo class  
 ??Foo f = new Foo();  
 ??// call the Bar()method  
 ??f.Bar();
Used to illustrate a code usage example. This tag is generally used in concert with the and/or the tag.

   The following code illustrates a possible use of   
 ???the Foo class:  
 ???    
 ?????// create an instance of the Foo class    
 ?????Foo f = new Foo();    
 ?????// call the Bar() method    
 ?????f.Bar();  
 ???
Used to indicate the exceptions that the current member can throw.

 ???if  is null
Used to control the format of the documentation output

  The Foo class...
Describes a method parameter.

  ???A  type representing?
Used to refer to a parameter previously described with the tag.
If  is null 
   the method will...
Used to supply further information about the member it describes.

  ??? The Foo type is thread-safe...
Describes the return value of a method.

  The length of
Used to create a cross-reference to another member (included .NET types, for example, the System.String type).
The     name="someString" /> represents...

Used to provide the summary of the member it precedes.

   This class is used as a bridge between...

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:

   ///    ///    ///    ///    ///

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 , , 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.
    3. ?
    Figure 2. Extracting XML Documentation: In Visual Studio, extracting XML comments requires only a few clicks and a file name entry.
  3. Enter a name in the XML Documentation File field and click OK.
  4. 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 binDebug 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.

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 binDebug 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 binDebug 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 binDebugDoc 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.

devxblackblue

About Our Editorial Process

At DevX, we’re dedicated to tech entrepreneurship. Our team closely follows industry shifts, new products, AI breakthroughs, technology trends, and funding announcements. Articles undergo thorough editing to ensure accuracy and clarity, reflecting DevX’s style and supporting entrepreneurs in the tech sphere.

See our full editorial policy.

About Our Journalist

Charlie Frank

Charlie has over a decade of experience in website administration and technology management. As the site admin, he oversees all technical aspects of running a high-traffic online platform, ensuring optimal performance, security, and user experience.
View Author
Show More