How to Use NDoc to Generate XML Documentation in .NET

Documentation of your system is one of the important tasks that have to be done for any software system or product. Without that it is not easy to track the code and the features that are incorporated in the system.

With proper documentation of your system it is possible to reduce the repeated work that is done without knowing what is there in your system. Instead of writing your own documentation by seeing the program logic it would be better if there is a tool to generate the documentation based on the comments that is given in the code.

One such tool that is of more help to the developers is the NDoc. If you use NDoc properly you can document your system in a very good manner than documenting manually.

Before you use the NDoc tool you have to ensure that it is installed in your system. Assuming that you are using the Visual Studio .Net for your development, you have to see whether you have the directory C:\Program Files\HTML Help Workshop in your system.

If you do not have that directory in your C drive then download and install the HTML Help Workshop in your system. After you have that directory in place you can download the NDoc tool from the websites sourceforge.net. You can search for the NDoc project in that site or download NDoc at http://sourceforge.net/projects/ndoc/

Use the web installer to install the NDoc tool since it will install the latest and the stable release in your system. Once you have installed the utility you are ready to do the documentation part needed. Refer to the readme.txt file that comes along with the NDoc tool for more information on installation of that tool if you are not having Visual Studio .Net in your system.

For using NDoc properly you have to code properly with the use of proper XML tags that are necessary for the generation of the documentation. There are many XML tags that are available for documentation. Some of them are, <c>, <code>, <example>, <para>, <param>, <remarks>, <returns>, <seealso>, and <summary>.

For using these tags within your code you have to place them in the comments tag. You should know the comments for documentation are placed within the “/**” and “*/”. You can also use the triple slash “///” for this purpose. The XML tags mentioned above are placed within these proper delimiters.

The <c> tag is used to place some text that are used in the codes. For example, if you have a method called AddMethod and you want to place this within your documentation, you can use as <c>AddMethod</c>.

Sometimes you may be willing to place some code within your documentation in that case you can use the <code> tag. Examples that are given in the documentation can be placed within the <example> tags. A typical example might have the <code> tag nested within the <example> tag.

You can have the comments of your code or system within the <summary> tag. An example of this would be,

/**
<summary>
This program is used to find the page rank of the URL that is given in text box.
<para>
We are using the Google API to determine the page rank of the given url.
</para>
</summary>
*/

The <para> tag can be used within the summary tag is you want to break the comments in the summary tag as paragraphs. For giving any additional information you can use the <remarks> tag. Tags like <returns> are used before the methods for identifying the return type of the methods.

The <param> tags are used to identify the parameters used in the methods. A tag called the <seealso> is used to redirect the user to some other definitions or part of the documentation. This is used as cross reference. For more details on the tags you can refer to http://msdn.microsoft.com/library/en-us/csref/html/vclrftagsfordocumentationcomments.asp

Once you have used the proper XML tags within your code then during the compilation of the application you can generate an XML file that contains the XML tags written in your code. The compiled assembly (.dll file) and the XML file thus generated are necessary to generate the system documentation properly using the NDoc tool. For example if your source file is UsingNDoc.cs, then you can compile in the command line using the command like:

csc /debug /t:library /out:bin/UsingNDoc.dll UsingNDoc.cs /doc:UsingNDoc.xml

The above command generates the UsingNDoc.dll for the source file UsingNDoc.cs. The xml tags are put in the file UsingNDoc.xml in the root directory of the application. The files UsingNDoc.dll and UsingNDoc.xml are used as inputs to the NDoc utility to generate the system documentation.

Once you start the NDoc tool it will ask for the assembly file and the xml file for generating the system documentation. Give these inputs by browsing to the location of the files. With the NDoc utility you can create documentation of the types MSDN, XML, LaTeX, Linear HTML, and JavaDoc.

You can select your option for generating using the “Select and Configure Documenter” section of the tool. Some other properties are also set in this section. You can set the OutputDirectory to which the output has to be given.

You can also set the OutputTarget which can be HTMLHelp, or Web or both. With the HtmlHelp a .chm file is generated. The supporting html files are also generated. With the Web choice it generates the html files needed and the index.html file which serves as the starting point.