TechBubbles Microsoft Technology BLOG

Documenting C# code with XML Comments

This article explains an easy and effective way of documenting your C# code. XML comments are the solution for generating a clean documentation for your code. Visual Studio environment allows you to generate a documentation file for your project. It helps your teammates and other people who using your code.

This post will explain how to use XML comments in code and how to generate XML help documents from those comments.

XML Comment Basics

XML comments can be used to all types except namespaces. The types can be Class,Module,Interface, Enum, properties, events and methods.

XML comments are inserted inline, directly in your source code. To insert an XML comment type three single “///”  immediately above definition.

/// <summary> /// Executes the sachet rule. /// </summary> /// <param name="inputRow">Input row of data.</param> /// <returns>True, if sachet exists else false.</returns> public override bool Execute(System.Collections.Generic.Dictionary<string, string>

inputRow) { if (!String.IsNullOrEmpty(inputRow["DOSEQTY"]) && inputRow["DOSEQTY"].

IndexOf("Sachet", StringComparison.OrdinalIgnoreCase) > -1) { return true; } return false; }

image

XML Comment in intellisense.

You can add elements that were not in the original XML skeleton. A list of common tags will appear in an IntelliSense  pop-up menu as shown in above figure.

Customizing XML Comments

Visual Studio provides a way to customize the default XML skeleton. Create .xml that includes your default comment templates. Save the file to the appropriate location based on your windows version.

Example: In Visual Studio 2008 the file has to save in the following path

“C:\Documents and Settings\<user>\Application Data\Microsoft\Visual Studio\9.0”.

Generating the XML Documentation File

The Visual Sharp compiler generates an XML document for your assembly with all the XML comments defined in the code. The sample Generated XML Document Excerpt as follows

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Microsoft.Cui.Data</name>
    </assembly>
    <members>
        <member name="T:Microsoft.Cui.Data.RuleStrategy">
            <summary>
            Rules strategy.
            </summary>
        </member>
        <member name="F:Microsoft.Cui.Data.RuleStrategy.ValidSeparator">
            <summary>
            Valid separator between fields.
            </summary>
        </member>
        
    </members>
</doc>
 
Generating Nicer Documentation
The XML generated by the Visual Csharp compiler is readable, but not the most user-friendly. A number of tools have been created to create nicer looking documentation that is easier to navigate.
The tool for generating the documentation can be downloaded from www.codeplex.com/sandcastle . The following post help you to use the sandbox for generating the documentation http://bloggingabout.net/blogs/jschreuder/archive/2006/08/11/Sandcastle_2C00_-a-documentation-tool-for-the-.Net-2.0-Framework.aspx
 
XML Comments in Visual Studio 2010

The Visual Studio 2010 editor is rewritten using Windows Presentation Foundation[WPF] and allows for rich visualizations. There is a new component named Managed Extensibility Framework(MEF) which makes it easier for registering add-ins with Visual Studio.

Source: MSDN Magazine may 2009

About the author

Kalyan Bandarupalli

My name is kalyan, I am a software architect and builds the applications using Microsoft .NET technologies. Here I am trying to share what I feel and what I think with whoever comes along wandering to Internet home of mine.I hope that this page and its contents will speak for me and that is the reason I am not going to say anything specially about my self here.

Add Comment

TechBubbles Microsoft Technology BLOG

Follow me

Archives

Tag Cloud