多數程式員都聽過 Java 隨附的 JavaDoc 工具,它能自動為程式碼產生 HTML 文件。C# 與 C# 編譯器也有類似功能,只不過產出的是 XML 而非 HTML——而採用 XML,反而讓文件更靈活、更容易再加工。
要使用 C# 的 XML 註解功能,註解必須以特殊的 /// 語法開頭。在 /// 之後,你可以用預先定義的標籤來註解程式碼,也可以插入自訂標籤,這些自訂標籤稍後都會被寫進產生的註解文件中。
<c>:將說明中的文字標記為程式碼
<code>:把多行內容標示為程式碼
<example>:指定使用方法或其他程式庫成員的範例
<exception>:指定可能發生的例外類別
<include>:以 XML XPath 語法引用其他檔案中的註解
<list>:在文件中插入清單
<para>:插入一個段落
<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);
}
}
}
編譯時加上 /doc 選項即可產生 XML 註解文件:
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 頁面呢?很簡單:你可以自行撰寫 XSL 來轉換這份 XML 註解文件,或者直接使用 Visual Studio .NET——在【工具】選單中選擇【產生註解 Web 網頁】,就能得到一整套說明專案或方案的 HTML 頁面,省去自己寫轉換樣式的工夫。