How to Use NDoc to Generate XML Documentation in .NET
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.
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
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.
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
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.
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.
<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>
can have the comments of your code or system within the <summary> tag. An
example of this would be,
program is used to find the page rank of the URL that is given in text box.
are using the Google API to determine the page rank of the given url.
<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
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:
/debug /t:library /out:bin/UsingNDoc.dll UsingNDoc.cs /doc:UsingNDoc.xml
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.
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.
Subscribe to our mailing list and receive new articles
through email. Keep yourself updated with latest
developments in the industry.
: We never rent, trade, or sell my email lists to
We assure that your privacy is respected