一、概述
程式的注釋在程式的編寫和維護中扮演着相當重要的角色,在生成工程的同時,說明文檔也随之而生了。.NET文檔生成工具用于将xml 文檔注釋生成格式類似MSDN的HTML幫助文檔,并編譯為CHM文檔(下文中将該工具稱為ADB,該軟體僅測試過.net2.0的程式集)。
二、ADB2.2的功能特點
1、支援合并多個程式集;
2、自動搜尋程式集及其引用的程式集對應的XML文檔(包括.Net自帶的程式集,如:system.xml);
3、靈活控制在文檔中顯示哪些成員,支援批量選擇(如:選擇所有公共的方法);
4、支援自定義文檔生成器,使用者可以通過繼承ADB提供的基類編寫自己的文檔生成器。
三、ADB2.2支援的注釋标記
标志名
說明
文法
參數
<summary>
對象的摘要,用于描述類型或類型成員
<summary>description</summary>
description:對象的摘要。
<remarks>
類型說明的補充資訊
<remarks>description</remarks>
description:成員的說明。
<param>
用于方法聲明的注釋中,以描述方法的一個參數
<param name='name'>description</param>
name:方法參數名。将此名稱用雙引号括起來 (" ")。
description:參數說明。
<returns>
用于方法聲明的注釋,以描述傳回值
<returns>description</returns>
description:傳回值的說明。
<value>
描述屬性所代表的值
<value>property-description</value>
property-description:屬性的說明
<example>
指定使用方法或其他庫成員的示例,通常涉及使用 <code> 标記
<example>description</example>
description: 代碼示例的說明。
<code>
提供了一種将多行訓示為代碼的方法。
<code>content</code>
content:希望将其标記為代碼的文本。
<exception>
指定哪些異常可被引發,該标記應用于方法定義。
<exception cref="member">description</exception>
cref:對可從目前編譯環境中擷取的異常的引用。
description:異常的說明。
<see>
從文本内指定連結
<see cref="member"/>
cref:對可以通過目前編譯環境進行調用的成員或字段的引用。
<para>
<para> 标記用于諸如<summary>,<remarks> 或 <returns> 等标記内,使您得以将結構添加到文本中。
<para>content</para>
content:段落文本。
<code>*
提供了一種插入代碼的方法。
<code src="src" language="lan" encoding="c"/>
src:代碼檔案的位置
language:代碼的計算機語言
encoding:檔案的編碼
<img>*
用以在文檔中插入圖檔
<img src="src"/>
src:圖檔的位置,相對于注釋所在的XML檔案
<file>*
用以在文檔中插入檔案,在頁面中表現為下載下傳連結
<file src="src"/>
src:檔案的位置,相對于注釋所在的XML檔案
<localize>*
提供一種注釋本地化的方法,名稱與目前線程語言不同的子節點将被忽略
<localize>
<zh-CHS>中文</zh-CHS>
<en>English</en>
...
</localize>
注:
1、*表示ADB自帶的文檔生成器擴充的标記;
2、其它不支援的标志将視為HTML标記。
四、生成文檔
1.步驟
(1) 點選添加,選擇要生成文檔的程式集;
(2) 選擇将在文檔中顯示該成員;
(3) 輸入标題,點選建立文檔。
2.主界面
3.批量選擇界面
4.生成的文檔——命名空間頁面
5.生成的文檔——類型頁面
6.生成的文檔——成員頁面
五、修改生成的文檔
使用SuperCHM或其它CHM制作工具,打開Pages"temp.hhp(相對于生成的CHM檔案)檔案進行修改,修改前請閱讀與目标CHM檔案同目錄下的"修改文檔.html"檔案