出處 http://dev.csdn.net/article/29/29045.shtm
簡介
大多數程序員可能都聽說過Java自帶的一個工具JavaDoc；使用它可以自動地爲你的代碼生成HTML文檔。C＃和C＃編譯器也有類似的功能，不過它生成的是XML，而不是直接生成HTML。不過使用XML會使得文檔更加靈活。
註釋語法
爲了使用C＃提供的XML註釋功能，你的註釋應該使用特殊的註釋語法（///）開頭。在///之後，你可以使用預先定義的標籤註釋你的代碼，也可以插入你自己定義的標籤。你定製的標籤將會在隨後加入到生成的註釋文檔中。
|
預定義的標籤 用處
<c> 將說明中的文本標記爲代碼
<code> 提供了一種將多行指示爲代碼的方法
<example> 指定使用方法或其他庫成員的示例
<exception> 允許你指定可能發生的異常類
<include> 允許你引用描述源代碼中類型和成員的另一文件中的註釋, 使用 XML XPath 語法來描述你的源代碼中的類型和成員。
<list> 向XML註釋文檔中插入一個列表
<para> 向XML註釋文檔中插入一個段落
<param> 描述一個參數
<paramref> 提供了一種指示一個詞爲參數的方法
<permission> 允許你將成員的訪問許可加入到文檔中
<remarks> 用於添加有關某個類型的信息
<returns> 描述返回值
<see> 指定鏈接
<seealso> 指定希望在“請參見”一節中出現的文本
<summary> 類型或類型成員的通用描述
<value> 描述屬性
|
例子
下面的例子爲我們常見的HelloWorld控制檯應用程序添加註釋：
|
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); } } } |
爲生成XML註釋文檔，我們在調用csc編譯源代碼時使用/doc選項：
|
csc /doc:HelloWorld.xml helloworld.cs
|
生成的結果文檔如下：
|
<?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頁面
你可能會問自己：我應該如何才能得到具有良好格式的HTML頁面呢？很簡單，你可以編寫自己的XSL來轉換生成的XML註釋文檔，或者使用Visual Studio.NET開發工具。通過使用VS.NET的【工具】菜單中的【生成註釋web頁】，你可以得到一系列詳細說明你的項目或解決方案的HTML頁面。下面就是通過VS.NET生成的註釋helloWorld程序的HTML頁面快照：