一.摘要

.Net允許開發人員在源代碼中插入XML註釋，這在多人協作開發的時候顯得特別有用。 C#解析器可以把代碼文件中的這些XML標記提取出來，並作進一步的處理為外部文檔。 這篇文章將展示如何使用這些XML註釋。 在項目開發中，很多人並不樂意寫繁雜的文檔。但是，開發組長希望代碼註釋盡可能詳細；項目規劃人員希望代碼設計文檔盡可能詳盡；測試、檢查人員希望功能說明書盡可能詳細等等。如果這些文檔都被要求寫的話，保持它們同步比進行一個戰役還痛苦。

為何不把這些信息保存在一個地方呢？？最明顯想到的地方就是代碼的註釋中；但是你很難通覽程序，並且有些需要這些文檔的人並不懂編碼。最好的辦法是通過使用XML註釋來解決這些問題。代碼註釋、用戶手冊、開發人員手冊、測試計劃等很多文檔可以很方便的從XML註釋中獲得。本文講解.Net中經常使用的XML註釋.主要使用C#語言j,.Net平臺支持的其他語言使用的XML註釋格式基本相同.並且在本系列文章的下一講中講解如何使用工具將XML註釋內容轉化為幫助文檔.

二.XML註釋概述

所有的XML註釋都在三個向前的斜線之後(///)。兩條斜線表示是一個註釋，編譯器將忽略後面的內容。三條斜線告訴編譯器，後面是XML註釋，需要適當地處理。

當開發人員輸入三個向前的斜線後，Microsoft Visual Studio .NET IDE 自動檢查它是否在類或者類成員的定義的前面。如果是的話，Visual Studio .NET IDE 將自動插入註釋標記，開發人員只需要增加些額外的標記和值。下面就是在成員函數前增加三個斜線，自動增加的註釋比如:

        
	/// <summary>
        /// 得到指定酒店的酒店信息
        /// </summary>
        /// <param name="hotelId">酒店Id</param>
        /// <param name="languageCode">語言碼.中文為zh-cn</param>
        /// <returns>酒店信息對象</returns>
        [OperationContract]
        OutHotelInfo GetHotelInfoByHotelId(string loginName, string loginPassword, string hotelId, string languageCode);
 

這裏嵌入的summary,param,returns標記僅僅是Visual Studio能夠識別的一部分標記，然而在智能感知IntelliSense中，並沒有把c#規範中所有的標記列出來，遺失的部分只能用手工插入。 這些手工標記是非常有用的，如果恰當地設置他們，對導出成外部說明文件將非常有幫助。

三.將註釋生成XML文件

在代碼中添加的註釋信息, 可以單獨提取出來, 生成XML文件. 在制作最後的幫助文件的時候會使用到這些註釋XML文件.

默認情況下是不生成註釋XML文件的.每個項目可以生成一個XML文件,需要我們在項目屬性中進行設置:

如上圖所示,在項目的"屬性頁"->"生成"中, 勾選"XML文檔文件"復選框,即可在編譯時生成註釋XML文件.生成路徑默認是和dll文件在同一個文件夾下,也可以自行修改.註意此處填寫的是相對路徑.

四.常見註釋標簽列表

註釋的使用很簡單,但是我們使用到的註釋很少.這是因為大部分項目中註釋的作用僅僅是給程序員自己看.如果想要生成類似MSDN這樣的文檔,我們需要了解更多的註釋標簽.下面是我整理的常用的註釋標簽: