C#使用XML註解

我相信progrmmer都有類似的經驗, 就是一兩個月之前寫的code, 日後在閱讀時, 如果沒有特別加上註解, 就要花腦筋和時間去回想, 當初code為何這樣寫, 嚴重一點的話, 甚至可能忘記當初的思路和流程.

因此,在程式碼加上註解是很重要的事, 因為它可以提高程式的可讀性和清晰度, 可方便日後程式碼的維護.

寫註解的方式, 最基本的寫法, 就是在註解說明之前加上//, 或把註解內容放在/* */之間,如下所示:

// This is a comment

/* This is a comment */

除了基本的寫法外, 你也可以用以XML為基礎的註解說明, 使用XML的好處是, 它是通用的資料格式, 易於作數據交換; 另外, 它可表達出結構化的資料. 而且還可以透過一些工具, 自動產生類別庫的參考手冊.

本文先介紹, 如何在C#程式碼中, 撰寫XML的註解說明, 下一篇文章再來介紹, 可以將XML檔自動轉成HTML help文件(類似MSDN help的說明文件)的工具.

XML參考文件的撰寫方式,是以///符號開頭, 並連接一個 XML 文件標籤(tag) , 標籤的名稱說明該段註解的目的. 下面的表格列出, 常用的XML標籤和說明.

XML標籤	說明
<summary>	摘要性的描述
<remark>	詳細的註解說明
<example>	使用範例, 通常<example>標籤中, 經常會包含多個<code>標籤
<code>	標示程式碼,被<code>標示住的程式碼,會和說明文件的一般文字不同格式
<c>	標示包含在一般文字段落中的程式碼
<see cref ="member">	在產生的說明文件中, 產生一個連接到其他成員的超連結
<seealso cref ="member">	和<see>標籤的功能差不多, 不過在說明文件中,<seealso>標籤會獨立到另一個區域作顯示
<exception>	說明程式丟出的異常
<param>	說明函式(method)的參數
<return>	說明函式(method)的回傳值
<value>	說明屬性(property)

若你想知道更詳細的內容, 可以到MSDN的XML Documentation的線上說明去查看.

下面的範例程式碼, 介紹XML說明文件的撰寫方式, 我們不要管程式碼的內容, 只要注意XML註解的寫法.


// XMLDocSample.cs
using System;

/// <summary>
/// Class level summary documentation goes here.
/// </summary>
/// <remarks>
/// Longer comments can be associated with a type or member
/// through the remarks tag
/// </remarks>
public class SomeClass
{
/// <summary>
/// Store for the name property
/// </summary>
private string myName = null;

/// <summary>
/// The class constructor.
/// </summary>
public SomeClass()
{
// TODO: Add Constructor Logic here
}

/// <summary>
/// Name property
/// </summary>
/// <value>
/// A value tag is used to describe the property value
/// </value>
public string Name
{
get
{
if (myName == null)
{
throw new Exception("Name is null");
}

return myName;
}
}

/// <summary>
/// Description for SomeMethod.
/// </summary>
/// <param name="s">
/// Parameter description for s goes here
/// </param>
/// <seealso cref="String">
/// You can use the cref attribute on any tag to reference a type or member
/// and the compiler will check that the reference exists.
/// </seealso>
public void SomeMethod(string s)
{
}

/// <summary>
/// Some other method.
/// </summary>
/// <returns>
/// Return results are described through the returns tag.
/// </returns>
/// <seealso cref="SomeMethod(string)">
/// Notice the use of the cref attribute to reference a specific method
/// </seealso>
public int SomeOtherMethod()
{
return 0;
}

}



加上註解後, 開啟VC 2008 專案的Properties 視窗, 選擇Build , 然後勾選XML documentation file, 即可在build之後, 產生一份XML的文件.

[圖 1] VC專案Build的設定




[圖 2] XML檔的內容