Click here to Skip to main content
Click here to Skip to main content

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.

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
{
 /// <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

    (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:

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 ...by 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!! Wink | ;)

License

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
Web Developer
United Kingdom United Kingdom
Irfan Patel is a Bachelor of Computer Application
He holds a Microsoft Certified Solution Developer Certificate and has worked extensively with COM and has been programming since 1998.
He has also trained more than 200 students and has taught various languages,RDBMS & platforms
from C,C++ to VB with Oracle,Access & MS SQLServer
from Vbscript,Javascript to ASP.
His expertise comes from various industries viz Jewellery, Shipping ,Automobile ,
Radio Frequency Devices, Photometers to name few.
Besides programming he loves music,singing,dancing, bike riding & cricket.

Comments and Discussions

 
GeneralMissing Tools > Build Comments....Command from IDE PinmemberPanayotis Matsinopoulos17-May-11 23:37 
QuestionIs there is a documentation tool liek NDoc which works for .Net 2.0 ??? PinmemberKalr211-Sep-07 22:20 
AnswerRe: Is there is a documentation tool liek NDoc which works for .Net 2.0 ??? PinmemberPete102416-Sep-07 21:58 
GeneralAccessing the value of a variable from NDoc Pinmemberprst12330-Jan-07 1:52 
Generalhelp PinmemberMyDays2-Aug-06 12:44 
QuestionNdoc? PinmemberDavid M. Kean23-Aug-04 14:38 

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

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

| Advertise | Privacy | Mobile
Web03 | 2.8.140709.1 | Last Updated 31 Aug 2004
Article Copyright 2004 by irfan patel
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid