Using XML annotations in C #

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.

预定义的标签 　　　　　 用处
<c>　　　　　　　　　　　　　　 将说明中的文本标记为代码
<code>　　　　　　　　　　　 提供了一种将多行指示为代码的方法
<example>　　　　　　　　　指定使用方法或其他库成员的示例
<exception>　　　　 允许你指定可能发生的异常类
<include>　　　　　　　　　　　　　 允许你引用描述源代码中类型和成员的另一文件中的注释, 使用 XML XPath 语法来描述你的源代码中的类型和成员。
<list>　　　　　　　　　　　　　 向XML注释文档中插入一个列表
<para>　　　　　　　　　　　　向XML注释文档中插入一个段落
<param>　　　　　　　　　　 描述一个参数
<paramref>　　　　　　　　 提供了一种指示一个词为参数的方法
<permission>　　　　　　　允许你将成员的访问许可加入到文档中
<remarks>　　　　　　　　　用于添加有关某个类型的信息
<returns>　　　　　　　　　　描述返回值
<see>　　　　　　　　　　　　 指定链接
<seealso>　　　　　　　　　 指定希望在“请参见”一节中出现的文本
<summary>　　　　　　　　 类型或类型成员的通用描述
<value>　　　　　　　　描述属性

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>