關於在C#中應用XML注釋標記的一點想法

1. 涉及的內容：

• Visual Studio 2005 開發環境
• 在C#中編寫注釋
• C#中的XML注釋標記
• Visual Studio 2005 IDE環境下的ToolTip自動提示

2. 發現的問題：

      在Visual Studio 2005 的C#開發環境下，利用自己編寫的XML注釋標記，可以實現調用函數時產生類似ToolTip的自動提示的效果，可以提示關於函數的功能和參數的資訊。

問題：採用Visual Studio 2005 IDE自動產生的XML注釋標記時，這種ToolTip只能提示<summary></summary>和<param></param>標籤下的內容（1、圖2）。<returns></returns>下的內容是不會提示的。換句話說，我覺得IDE提示的資訊不夠豐富，我想讓它提示更多的資訊，並且排版也要清晰、美觀。

圖1

圖2

對應的XML注釋：

圖1和圖2對應的XML注釋代碼
/// <summary>
/// 將屬性資訊寫入資料庫。
/// </summary>
/// <param name="toolAttributeWithValue">包含屬性和屬性值的ToolAttributeWithValue數組。</param>
/// <returns>成功-true；失敗-false。</returns>
public static bool WriteAttribute(ToolAttributeWithValue[] toolAttributeWithValue) 

3. 實現的效果

• 要能提示函數功能
• 要能提示函數參數
• 要能提示函數傳回值
• 要能實現不同資訊的分行顯示（排版）  
• 圖3展示了我想要實現的效果。

 
圖3

對應的XML注釋代碼：

圖3 對應的XML注釋代碼
/// <summary>
/// 功能：將屬性資訊寫入資料庫。<para />
/// <param name="toolAttributeWithValue">
/// 參數：包含屬性和屬性值的ToolAttributeWithValue數組。<para /></param>
/// <returns>
/// 返回：成功-true；失敗-false。</returns>
/// </summary>
public static bool WriteAttribute(ToolAttributeWithValue[] toolAttributeWithValue)

4. 實現方法：

      將函數傳回值也加入ToolTip提示：

      預設的XML注釋標籤的相片順序下， <summary><param><returns>是三個單獨的標籤對。這種情況下，當你在IDE中指向函數名時，ToolTip只包含<summary>標籤下的內容，即參數和返回都不會提示。所以這裡要對XML注釋標記的排列順序做一下調整。讓<param><returns>成為<summary>的子項目。對應的XML注釋代碼如下所示：

調整標記順序後的XML注釋代碼
/// <summary>
/// 功能：將屬性資訊寫入資料庫。
/// <param name="toolAttributeWithValue">參數：包含屬性和屬性值的ToolAttributeWithValue數組。</param>
/// <returns>返回：成功-true；失敗-false。</returns>
/// </summary>

      到這裡函數功能、參數、傳回值都可以提示出來，但是它們是在一行顯示的，沒有分行，即沒有排版效果。下面來實現分行的效果。這裡要用到一上HTML標記，<para />。按道理說，這裡應該用<br />更合適，但是我用<br />沒能實現分行的效果，而<para />可以。對就的XML注釋代碼如果所示：

實現完整效果的XML注釋代碼
///<summary>
/// 功能：將屬性資訊寫入資料庫。<para />
///
/// <param name="toolAttributeWithValue">
/// 參數：包含屬性和屬性值的ToolAttributeWithValue數組。<para /></param>
/// <returns>
/// 返回：成功-true；失敗-false。</returns>
/// </summary>

5. 可能的問題：

      這裡不討論如何用Visual Studio 2005 提取XML注釋，產生XML文檔。本文對<summary>、<param>、<returns>三個標籤對的包含順序的調整，可能會影響產生的XML文檔。這個問題我沒做驗證，因為我現在不會用Visual studio 2005產生XML文檔。

這是在“部落格園”寫的第一篇隨筆，這個可以插入代碼塊的功能實在是太棒了！