Quick C# Documentation using XML

• Download source files - 49.8 Kb

Introduction

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
{
 /// <summary>
 /// This project shows how to create XMl documentation in C#
 /// </summary>
 public class TestXMLdoc
 {
  /// <summary>
  /// m_iTestVar is a module level test variable for storing int 
  /// </summary>
  private int m_iTestVar;
  /// <summary>
  /// m_sTestVar is a module level test variable for storing string 
  /// </summary>
  private string m_sTestVar;
  /// <summary>
  /// TestXMLdoc is the constructor 
  /// </summary>
  public TestXMLdoc()
  {
   //
   // TODO: Add constructor logic here
   //
  }
  /// <summary>
  /// TestReturnBack is a test method which
 /// simply takes a name and returns it back.
  /// </summary>
  /// <param name="sName"></param>
  /// <returns></returns>
  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

   (or)

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:

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.

   

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 ...by now, you must be curious and must have already clicked the class name within.

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 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!! ;)