NET中的規範標準註釋(一) -- XML註釋標籤講解

時間  2020-09-20
標籤 規範 標準 註釋 xml 標籤 講解 欄目 XML 简体版
原文   原文鏈接

一.摘要

 

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

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

二.XML註釋概述

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

當開發人員輸入三個向前的斜線後，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文件,須要咱們在項目屬性中進行設置:post

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

四.常見註釋標籤列表

註釋的使用很簡單,可是咱們使用到的註釋不多.這是由於大部分項目中註釋的做用僅僅是給程序員本身看.若是想要生成相似MSDN這樣的文檔,咱們須要瞭解更多的註釋標籤.下面是我整理的經常使用的註釋標籤:編碼

標籤名稱spa

說明

語法

參數

<summary>

<summary> 標記應當用於描述類型或類型成員。使用 <remarks> 添加針對某個類型說明的補充信息。

<summary> 標記的文本是惟一有關 IntelliSense 中的類型的信息源，它也顯示在 對象瀏覽器 中。

<summary>

Description

</summary>

description:對象的摘要。

<remarks>

使用 <remarks>標記添加有關類型的信息，以此補充用 <summary> 指定的信息。此信息顯示在對象瀏覽器中。

<remarks>

Description

</remarks>

description:成員的說明。

<param>

<param> 標記應當用於方法聲明的註釋中，以描述方法的一個參數。

有關 <param> 標記的文本將顯示在 IntelliSense、對象瀏覽器和代碼註釋 Web 報表中。

<paramname='name'>

description

</param>

name:方法參數名。將此名稱用雙引號括起來 (" ")。

description:參數說明。

<returns>

<returns> 標記應當用於方法聲明的註釋，以描述返回值。

<returns>

Description

</returns>

description:返回值的說明。

<value>

<value> 標記使您得以描述屬性所表明的值。請注意，當在 Visual Studio .NET 開發環境中經過代碼嚮導添加屬性時，它將會爲新屬性添加 <summary> 標記。而後，應該手動添加 <value> 標記以描述該屬性所表示的值。

<value>

property-description

</value>

property-description:屬性的說明

<example>

使用 <example> 標記能夠指定使用方法或其餘庫成員的示例。這一般涉及使用 <code> 標記。

<example>

Description

</example>

description: 代碼示例的說明。

<c>

<c> 標記爲您提供了一種將說明中的文本標記爲代碼的方法。使用 <code> 將多行指示爲代碼。

<c>

Text

</c>

text :但願將其指示爲代碼的文本。

<code>

使用 <code> 標記將多行指示爲代碼。使用<c>指示應將說明中的文本標記爲代碼。

<code>

Content

</code>

content:但願將其標記爲代碼的文本。

<exception>

<exception> 標記使您能夠指定哪些異常可被引起。此標記可用在方法、屬性、事件和索引器的定義中。

<exception

cref="member">

Description

</exception>

cref:

對可從當前編譯環境中獲取的異常的引用。編譯器檢查到給定異常存在後，將 member 轉換爲輸出 XML 中的規範化元素名。必須將 member 括在雙引號 (" ") 中。

有關如何建立對泛型類型的 cref 引用的更多信息，請參見 <see>

description:異常的說明。

<see>

<seealso>

<see> 標記使您得以從文本內指定連接。使用 <seealso> 指示文本應該放在「另請參見」節中。

<seecref="member"/>

cref:

對能夠經過當前編譯環境進行調用的成員或字段的引用。編譯器檢查給定的代碼元素是否存在，並將 member 傳遞給輸出 XML 中的元素名稱。應將 member 放在雙引號 (" ") 中。

<para>

<para> 標記用於諸如<summary>，<remarks> 或 <returns> 等標記內，使您得以將結構添加到文本中。

<para>content</para>

content:段落文本。

<code>*

提供了一種插入代碼的方法。

<code src="src" language="lan" encoding="c"/>

src:代碼文件的位置

language:代碼的計算機語言

encoding:文件的編碼

<img>*

用以在文檔中插入圖片

<imgsrc="src"/>

src:圖片的位置，相對於註釋所在的XML文件

<file>*

用以在文檔中插入文件，在頁面中表現爲下載連接

<filesrc="src"/>

src:文件的位置，相對於註釋所在的XML文件

<localize>*

提供一種註釋本地化的方法，名稱與當前線程語言不一樣的子節點將被忽略

<localize>

<zh-CHS>中文</zh-CHS>

<en>English</en>

...

</localize>

 

 

五.註釋與幫助文檔

完善註釋信息的最終目的就是爲了生成MSDN同樣的程序幫助文檔,此文檔將在項目整個生命週期中被各類角色使用:開發人員經過此文檔維護程序, 測試人員經過此文檔瞭解業務邏輯, 項目管理人員將此文檔用做項目說明等等.

因此要了解列表中這些不常見的註釋究竟有何做用,就要和最終的幫助文檔關聯起來.下面經過示例講解註釋標籤在幫助文件中的做用.有關如何生成幫助文件,將在本系列下一篇文章中講解.

先簡單看一下幫助文件的樣子.咱們都看過MSDN幫助文檔,使用註釋XML文件生成的幫助文件後綴名是chm,打開後和MSDN基本同樣:

image

 

本示例的命名空間是XmlCommentClassDemo, 其中包含兩個類:

UserBL是包含方法的類.

UserInfo是一個模型類.裏面只有UserId和UserName兩個屬性.

 

(1)類註釋


看一下UserBL類的註釋代碼:

    /// <summary>
    /// 用戶對象業務邏輯層.
    /// </summary>
    /// <remarks>
    /// 2009.01.01: 建立. ziqiu.zhang <br/>
    /// 2009.01.23: 增長GetUserName和GetUserId方法. ziqiu.zhang <br/> 
    /// </remarks>
    public class UserBL
    {...}

Summary標籤的內容在命名空間類列表中顯示,如上圖.remarks標籤的內容則顯示在類頁面中,以下圖:

image

對比之前的註釋規範,下面的註釋是咱們規定在建立一個新的文件時須要添加到頭部的註釋:

/***************************************************************************************
 * *
 * *        File Name        : HotelCommentHeaderInfo.cs
 * *        Creator            : ziqiu.zhang
 * *        Create Time        : 2008-09-17
 * *        Functional Description  : 酒店的點評頭模型。包括酒店實體對應的點評頭，酒店的OutHotelInfo信息
 *                                    ，酒店實體的Tag信息集合。
 * *        Remark      : 
 * *
 * *  Copyright (c) eLong Corporation.  All rights reserved. 
 * ***************************************************************************************/

添加此註釋塊的目的很好.可是很難推廣.由於這段註釋並不能被編譯器識別,也沒法添加到註釋XML文件中用於生成幫助文件. 格式不容易記憶,想添加的時候只能從別的複製過來後修改.公司缺乏完善的Code Review機制因此最後不少文件都沒有此註釋塊.

相比較使用.NET本身的註釋語言,不只"敏捷",並且會成爲幫助文件中的描述.

 

 

 

 

(2)方法註釋

類的註釋比較簡單.爲了樣式經常使用註釋標籤的效果, 我在方法的註釋中使用了儘量多的註釋標籤.代碼以下:

        /// <summary>
        ///     根據用戶Id獲得用戶名.
        ///     <para>
        ///         此處添加第二段Summary信息,在MSDN中不多使用.因此不推薦使用.
        ///     </para>  
        /// </summary>
        /// <remarks>
        ///     若是沒有找到用戶則返回null.<br/>
        ///     <paramref name="userId"/> 參數爲正整數.<br/>
        ///     用戶Id模型屬性定義參見<see cref="UserInfo.UserId"/><br/>
        ///     相關方法:<seealso cref="UserBL.GetUserId"/>
        /// </remarks>
        /// <param name="userId">用戶Id</param>
        /// <returns>用戶真實姓名</returns>
        /// <example>
        ///     返回用戶id爲100的用戶真實姓名:
        ///     <code>
        ///         private string userName = string.Empty;
        ///         userName = UserBL.GetUserName(100);
        ///     </code>
        ///     返回的用戶名可能爲null,使用時要先判斷:<br/>
        ///     <c>if(userName!=null){...}</c>
        /// </example>
        /// <exception cref="System.ApplicationException">
        ///     若是用戶Id小於0則拋出此異常
        /// </exception>
        public static string GetUserName(long userId)
        {
            string result = string.Empty;
            if (userId < 0)
            {
                throw new System.ApplicationException();                
            }
            else if (userId == 0)
            {
                result = null;
            }
            else
            {
                result = "Robert";
            }
            return result;
        }

 

接下來經過圖片進行詳細講解.首先是查看類成員時的截圖:

image

點擊方法後的截圖:

image

 

須要注意的幾點:

1) 最開始seealso標籤添加在了remarks標籤中,因此在See Also區域沒有添加上方法的鏈接. 解決方法是把seealso標籤放在summary標籤中.

2) 異常類的cref屬性須要設置成編譯器能夠識別的類, 這樣才能夠在幫助文檔中點擊.好比上面的System.ApplicationException異常點擊後進入微軟的在線MSDN查詢.若是是本身定義的異常, 須要此異常類也在你的幫助文件中.通常提供註釋XML和依賴DLL便可.

(3) 屬性的註釋

屬性的註釋也很簡單.和類不一樣的地方在於屬性要使用<value>標籤而不是<remarks>進行描述:

        private string m_UserName = string.Empty;
        /// <summary>
        /// 用戶真實姓名
        /// </summary>
        /// <value>用戶真實姓名字符串.默認值爲空.</value>
        public string UserName
        {
            get { return m_UserName; }
            set { m_UserName = value; }
        }

效果如圖:

image

六.總結

本文講解了.NET中的XML註釋標籤, 以及最後在幫助文檔中的做用.

瞭解了標籤的使用,在下篇文章中將告訴你們如何使用工具生成本文示例中的幫助文件.

出處：http://www.cnblogs.com/zhangziqiu/archive/2009/01/23/XmlComment.html

相關文章
相關標籤/搜索
每日一句
    每一个你不满意的现在，都有一个你没有努力的曾经。
本站公眾號
   歡迎關注本站公眾號,獲取更多信息
聯繫我們 最近搜索 最新文章 沪ICP备13005482号-10 MyBatis教程 SQL 教程 MySQL教程 Java 教程 Thymeleaf 教程 Hibernate教程 Spring教程 Redis教程