Using XML annotations in C #

Xml

Brief introduction

Most programmers may have heard of a Java-brought tool Javadoc, which automatically generates HTML documents for your code. C # and C # compilers also have similar functionality, but instead of generating HTML directly, it generates XML. However, using XML will make the document more flexible.

annotation syntax

In order to use the XML annotation functionality provided by C #, your annotations should begin with a special annotation syntax (///). After///, you can annotate your code with predefined tags, or you can insert your own defined tags. Your custom tags will then be added to the generated annotation document.

Predefined label usefulness

<c> mark text in the description as code

<code> provides a way to indicate multiple lines as code

<example> specify examples of using methods or other library members

<exception> allows you to specify possible exception classes

<include> allows you to refer to a comment in another file that describes the type and members of the source code, using XML XPath syntax to describe the types and members in your code.

<list> Insert a list into the XML annotation document

<para> insert a paragraph into the XML annotation document

<param> describe a parameter

<paramref> provides a way to indicate that a word is a parameter

<permission> allows you to add a member's access permission to the document

<remarks> to add information about a type

<returns> Description return value

<see> Specify Links

<seealso> Specify the text that you want to appear in the See Also section

<summary> generic description of type or type members

<value> Description Properties

Example

The following example adds a comment to our common HelloWorld console application:

Using System;

Namespace HelloWorld
{
<summary>
Sample Hello World in C #
</summary>
public class HelloWorld
{
<summary>
Console Application Entry Point
<param name= "args" >command line arguments</param>
<returns>status Code of 0 on successful run</returns>
</summary>
public static int Main (string[] args)
{
System.Console.WriteLine ("HelloWorld");
String name = System.Console.ReadLine ();

return (0);
}
}
}

To generate an XML annotation document, we use the/doc option when calling the CSC to compile the source code:

Csc/doc:helloworld.xml HelloWorld.cs

The resulting document is as follows:

<?xml version= "1.0"?>

<doc>

<assembly>

<name>XMlComment</name>

</assembly>

<members>

<member name= "T:helloworld.helloworld" >

<summary>

Sample Hello World in C #

</summary>

</member>

<member name= "M:helloworld.helloworld.main (system.string[)" >

<summary>

Console Application Entry Point

<param name= "args" >command line arguments</param>

<returns>status Code of 0 on successful run</returns>

</summary>

</member>

</members>

</doc>

HTML page

You might ask yourself: how do I get an HTML page with a good format? Quite simply, you can write your own XSL to transform the generated XML annotation document, or use the Visual Studio.NET development tool. By using the Generate Comment Web page from the Vs.net Tools menu, you can get a series of HTML pages detailing your project or solution. The following is an HTML page snapshot of the annotation HelloWorld program generated by vs.net: