Click here to Skip to main content
13,350,822 members (73,586 online)
Click here to Skip to main content
Add your own
alternative version


34 bookmarked
Posted 22 Aug 2004

Quick C# Documentation using XML

, 30 Aug 2004
Rate this:
Please Sign up or sign in to vote.
This article shows how to create documentation in C# in a simple and fast way. Like my previous articles, this one too focuses beginner to intermediate level.


This article shows how to create documentation in C# in a simple and fast way. Like my previous articles, this one too focuses beginner to intermediate level. Advance developers please scroll to the bottom of this article. Remember the days when programmers used to work hard to do the documentation? Trust me, it's a huge difference nowadays. Now, all a programmer need to do is to embed the XML documentation right into the code and let Visual Studio .NET perform the rest.

Note: If you are very new to XML, click here to checkout my previous article on XML walkthrough.

To start with, just follow the instructions step by step.

Step By Step Walkthrough:
  1. Go to File->New->Blank Solution.
  2. Select Visual C# Projects in Project Types.
  3. Select ClassLibrary in Templates.
  4. Type, for e.g. TestXMLdoc, in the Name textbox.

Creating a simple class XML file (the class which will have the comments which will be read by our Visual Studio .NET to create the XML documentation)

Replace the code in the class with the following:

using System;
namespace TestXMLdoc
 /// <span class="code-SummaryComment"><summary></span>
 /// This project shows how to create XMl documentation in C#
 /// <span class="code-SummaryComment"></summary></span>
 public class TestXMLdoc
  /// <span class="code-SummaryComment"><summary></span>
  /// m_iTestVar is a module level test variable for storing int 
  /// <span class="code-SummaryComment"></summary></span>
  private int m_iTestVar;
  /// <span class="code-SummaryComment"><summary></span>
  /// m_sTestVar is a module level test variable for storing string 
  /// <span class="code-SummaryComment"></summary></span>
  private string m_sTestVar;
  /// <span class="code-SummaryComment"><summary></span>
  /// TestXMLdoc is the constructor 
  /// <span class="code-SummaryComment"></summary></span>
  public TestXMLdoc()
   // TODO: Add constructor logic here
  /// <span class="code-SummaryComment"><summary></span>
  /// TestReturnBack is a test method which
 /// simply takes a name and returns it back.
  /// <span class="code-SummaryComment"></summary></span>
  /// <span class="code-SummaryComment"><param name="sName"></param></span>
  /// <span class="code-SummaryComment"><returns></returns></span>
  public string TestReturnBack(string sName)
   return "Your name is " + sName;

Compiling your application after specifying the documentation filename

Note: If you are not using the Visual Studio .NET IDE, you should go for the first one from the following optionss:

  1. At the compile time, you just need to specify the file name like the following:
    csc testXMLdoc.cs /doc:testXMLdoc.xml


  2. If you are using the powerful Visual Studio .NET IDE, then follow these steps:
    1. Go to to the Solution Explorer.
    2. Right click the project and go to Properties.
    3. This will open a dialog box.
    4. Locate the configuration properties -> Build
    5. Specify the output path, and XML documentation file name, say TestXMLdoc. That's it.
    6. Compile it and it will create the file at the specified location.

Unlike Java, Microsoft Visual C# generates XML documentation instead of HTML, and as we know about XML, it's mould-able and later can be used anywhere else we need. The following is a list of tags along with their description which can be used in creation of XML documentation.

  • <c>

    This will textually include provided code in a single line.

    E.g.: <c> int i = 0 ; </c>

  • <code>

    This will textually include provided code in multiple lines (snippet).

  • <example>

    This will include a code example.

  • <exception>

    This will force the compiler whether it matches a possible exception.

  • <include>

    This will fetch the documentation from an external file. Same as #include in scripting languages.

  • <list>

    This will insert a list into the documentation file.

  • <param>

    This specifies the parameters of the method and makes the compiler verify it.

  • <paramref>

    This will mark a parameter.

  • <permission>

    This will determine the access permissions.

  • <remarks>

    This will include a descriptive text.

  • <returns>

    This will mark the return value of a member.

  • <see>

    It is a reference to a related item.

  • <seealso>

    This is similar to the 'See also' section of the MSDN help.

  • <summary>

    A summary of the member item. Normally, Visual Studio .NET prepares this automatically along with its close tag the moment you type.

  • /// (three slashes) in its editor.
  • <value>

    This is nothing but a property.

Opening the XML documentation file

  1. Go to the specified path (by default, your application's bin/Debug).
  2. Open the XML file (in our case, TestXMLdoc.xml) in Internet Explorer.
  3. Check out: it should look like the following:

Generated XML File

Creating an HTML document file automatically

Wasn't that fun? It was.. I know. But that was just a trailer, let's see the whole movie.

  1. Go to menu Tools->Build Comment Web Pages.

    Build Comment Dialog Box

  2. On the dialog box, click OK to see the magic (you may change the options as per your need but since we have a single class, let's leave it to default ones).
  3. Click on the name of the solution on the created web page.
  4. Now, click on the project name in the displayed tree.
  5. And now, you must be curious and must have already clicked the class name within.

Sample Image - TestXMLdoc.jpg

That's the result of your patience, hard work and cooperation.

Note: The above example was for people who need a tool to suffice their minimum requirements. For advance documentation, you would like to opt for a more sophisticated tool like NDoc Code Documentation Generator for .NET.

NDoc generates class library documentation from .NET assemblies and the XML documentation files generated by the C# compiler (or with an add-on tool for VB.NET). And the output looks like the following:

NDOC sample output

NDoc uses pluggable documenters to generate documentation in several different formats, including the MSDN-style HTML Help format (.chm), the Visual Studio .NET Help format (HTML Help 2), and MSDN-online style web pages.

You can download the latest version: NDOC 1.3 Beta or NDOC 1.2.

Thanks to Ms. Manisha Mahajani for reviewing the article for errors.

Njoi programming!! ;)


This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


About the Author

irfan patel
Instructor / Trainer
India India
Irfan Patel is a Bachelor of Computer Application
He holds a MCSD, MCP.NET, ITIL Certifications and has worked extensively with C#, ASP.Net, SQL Server since 1998.
He has also trained various programming languages and tools, RDBMS & OS platforms to more than 1000 students.

His expertise comes from various industries viz Jewellery, Shipping ,Automobiles , RFID projects, Ticket Reservation systems and e-commerce websites.

Besides teaching and programming he loves music, singing, dancing, bikes & following his favourite football team Chelsea.

You may also be interested in...


Comments and Discussions

GeneralMissing Tools > Build Comments....Command from IDE Pin
Panayotis Matsinopoulos18-May-11 0:37
memberPanayotis Matsinopoulos18-May-11 0:37 
QuestionIs there is a documentation tool liek NDoc which works for .Net 2.0 ??? Pin
Kalr211-Sep-07 23:20
memberKalr211-Sep-07 23:20 
AnswerRe: Is there is a documentation tool liek NDoc which works for .Net 2.0 ??? Pin
Pete102416-Sep-07 22:58
memberPete102416-Sep-07 22:58 
GeneralAccessing the value of a variable from NDoc Pin
prst12330-Jan-07 2:52
memberprst12330-Jan-07 2:52 
Generalhelp Pin
MyDays2-Aug-06 13:44
memberMyDays2-Aug-06 13:44 
QuestionNdoc? Pin
David M. Kean23-Aug-04 15:38
memberDavid M. Kean23-Aug-04 15:38 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Permalink | Advertise | Privacy | Terms of Use | Mobile
Web02 | 2.8.180111.1 | Last Updated 31 Aug 2004
Article Copyright 2004 by irfan patel
Everything else Copyright © CodeProject, 1999-2018
Layout: fixed | fluid