Tutkiun

Wondering how to build an automated reference document like java doc in .NET? C# has a built in system which converts special comments into document. But, the document is in XML format and that’s why it can be used with variety of standards. Best part of this is, the tools come with all versions of Microsoft’s Visual Studio.

Many of the developers simply don’t know about such a functionality and waste lot of their time in commenting in traditional ways. C Sharp uses various tags which have different meanings.

We will see one by one their meaning and actual usage.

While coding, you might observe a triple slash comments (“///”) in your code. The first two slashes tells compiler that it is an comment and tells compiler to ignore the content that follows. The third slash specifies it’s an XML comment and should be handled appropriately. The compiler assumes that the input is a valid XML and parses accordingly.

Summary Tag-

Once developer enter three forward slashes “///”, Visual studio IDE directly inserts <summary> tag. Summary tag describes  a type or a member type.

For Ex. <summary>MyMethod is a method in the MyClass class.</summary>

para-

This tag indicates that the text in between opening and closing
tags should be formatted within a paragraph. It is used with summary or returns to format text between those tags.

For Ex. <para>Here's how you could make a paragraph in a description.</para>

see-

See tag is somewhat similar to anchor tag in HTML it is used to reference other entities (such as classes) in the project. It can be used within other tags as well as independently.

For Ex. <seealso cref="System.Configuration"/>

code-

Used to specify one or more lines of code in between XML comments.

For Ex.
<code>
class MyClass
{
public static int Main()
{
return GetZero();
}
}
</code>

c-

Similar to code tag but c tag is used to when we need to specify code not more than one line. c tag can be used to specify markup for line of code.

For Ex. <c>double SalesTotal = 12</c>

example-

This tag may be used to describe an example of using a particular method or class. It is possible to include code samples within the example tag by making use of either the c or code tags.

For Ex. <example> This sample shows how to call a method</example>

returns

The returns tag should be used in the comment for a method declaration to describe the return value of function.

For Ex. <returns>description</returns>

remarks

The remarks tag is used to add additional information about the member, supplementing the information specified with summary. The information in remark tag is represented in object browser.

list

The list tag is used in other comment tags to define a specialized list. The type of list is defined by the type attribute, which can have the values bullet, number, or table. Tags such as listheader, term, item, description are used inside list tag to represent elements in list.

For Ex.
<list type="bullet" | "number" | "table">
<listheader>
<term>term</term>
<description>description</description>
</listheader>
<item>
<term>term</term>
<description>description</description>
</item>
</list>

paramref

If text within a comment needs to have a parameter specially identified, then paramref is the tag to use. It is inserted in the text in the location where the parameter text should appear. The main purpose of this tag is to identify the name of a parameter that should be formatted in a special way. It has one attribute, name, which is the name of the parameter that would appear in the text.

For Ex.
<paramref>strRootDirectory</paramref>.

value

The value tag defines the meaning of a property member. It is used just like theremarks tag is used for classes and the summary tag is used for other members.

For Ex.
<value>The SourceXML property contains the XML that will be used in the transformations by the member functions for this class.</value>

HTML Equivalent to XML Comments

Converting from comments to XML

Hey, we learned about various tags present in XML comments and their use. But, where is documentation file you was talking about?

Well, just go to
Project Properties > Build
Check box labelled “XML Documentation file”
Provide suitable name to XML file.

Now, on whenever you build the project the comment documentation will be automatically generated in XML file you have specified. This file is present in debug or release in ‘bin’ folder.

Converting from XML to Help files

At this point, XML generated is not ready to use. It needs processing to convert it into format easily recognised by humans. This can be done by an excellent software “Sandcastel”. This software converts those XML files into MSDN styled, comprehensive documentation by reflecting over the source assemblies and optionally integrating XML Documentation Comments.
If you don’t want to install any software on your machine then you might want to look at XSL template to convert XML to HTML by Emma Burrows

Like this article or have something to say on commenting in Visual Studio? Comment down your opinions.