NDoc1.3.1使用手冊

目錄

NDoc1.3.1使用手冊????1

目錄????2

修改歷史紀錄????3

1、NDoc簡介????4

2、安裝（for VS2003）????4

3、使用????7

3.1 配置您的C#項目????7

3.2 "裝飾"您的代碼????10

3.3、新建NDoc項目????25

4 OVERLOAD（重載）????35

1、NDoc簡介

NDoc 可以將 C#.NET 編譯生成的程序集和對應的 /doc XML 文檔，自動轉換成如 .NET Framework SDK 類庫文檔或者 MSDN Library 在線 .NET 類庫文檔形式的代碼文檔，讓您快速擁有專業級的類庫API 文檔。

2、安裝（for VS2003）

解壓后，雙擊"Setup.exe"進入安裝界面，如下圖：

?

點擊"下一步"：

?

選擇要安裝的路徑，點擊"下一步"，如下圖：

?

?

選擇"同意"，點擊"下一步"繼續，再點"下一步"進行安裝，如下圖：

?

?

點擊"關閉"完成安裝，如下圖：

?

?

?

3、使用

開始之前，您需要準備以下工具，HTML Help 1 文件，也就是 CHM 文件，是很常見的應用程序幫助文件格式，在 Visual Studio .NET 發布之前，MSDN 一直采用的就是 HTML Help 1 格式。

如果您準備創建 HTML Help 1 (*.CHM)文件，請確認您已經安裝好 Microsoft's HTML Help Workshop。此安裝包已包含必需的 HTML Help 1 編譯器，在與NDoc同目錄下有此安裝文件（htmlhelp.EXE）,按提示安裝即可。

3.1 配置您的C#項目

首先，您應該確認，您已經打開了 C# 項目的 /doc 開關，當 Visual Studio .NET 編譯時，每次都會生成相應的 XML 文檔。

如果沒有特殊情況，請讓項目輸出的程序集名稱和 XML 文檔文件名、僅僅擴展名不同(比如程序集是 NDoc.Test.dll/NDoc.Test.exe，XML 文檔是 NDoc.Test.xml)。在 NDoc 中，當您加入某程序集時，NDoc 會自動查找這樣的"同名" XML 文件。如果找到，就會嘗試自動將它當作該程序集的 XML 文檔。這樣會簡化您的操作。

此處以"Example069-繪制藝術圖案（1）"為例，打開"項目|屬性"對話框，如下圖：

?

找到"程序集名稱"，如下圖：

選擇左框中的"配置屬性"，在右側設置 XML 文檔文件為程序集名稱(擴展名改為 xml)。別忘了設置此項之前，選擇"所有配置"，讓 Debug 或 Release 配置下，都自動生成 XML 文檔，如下圖：

點擊"確定"?，F在，每次使用 VS.NET 編譯您的程序集，都會自動從源代碼中提取所有的 XML 注釋，生成 XML 文檔文件（但是每個不同的項目都得設置一次），如下圖：

如果您使用的不是 Visual Studio .NET，您同樣應該嘗試打開 C# 編譯器的 /doc 選項。

3.2 "裝飾"您的代碼

您在代碼中書寫的 XML 注釋越多，最終生成的代碼文檔越專業。程序集的使用者越能從中獲得幫助。

一般而言的最低要求，對于每一個公共類型，應該給它的所有公共的和受保護的成員添加 <summary> 注釋，以描述該成員表示什么意義或者會做些什么動作。

可以從VS.NET的任務列表中查看是否注釋完全，如下圖：

雙擊它們就可以定位到未添加注釋的位置。

如果在下面的選項中找不到"任務列表"，可以點擊"視圖|其它窗口|任務列表"打開，如下圖：

在 VS.NET 中，C# 代碼編輯器，提供了一些自動完成的功能，幫助我們創建基本的 XML 注釋。

比如如下的代碼:

public class MyClass() {

public MyClass( string s ) { }

}

把光標移動到 MyClass 構造函數的上面一空行，敲 '/' 鍵三次，VS.NET 自動創建一個 summary XML 文檔塊（在VS2005中更可以使用GhostDoc更方便地生成注釋，詳細內容請見《[技術文檔]GhostDoc2.1.1使用手冊》）:

public class MyClass() {

/// <summary>

///

/// </summary>

/// <param name="s"></param>

public MyClass( string s ) { }

}

這種操作對于所有可以書寫 XML 注釋文檔的成員都有效。另外，在以 '///' 開頭的 XML 注釋行中，敲入 '<' 字符，VS.NET 自動感知功能將自動顯示可用的 XML 注釋標記列表。不過，這個列表不包括 NDoc 所支持的額外的標記，這些額外的標記，您需要手工敲入。

NDoc 可以配置為輸出所有的成員，包括私有的和內部的成員，雖然這些成員無法在程序集外部被調用，但如果您需要，您可以同樣為這些成員添加 XML 注釋，NDoc 會幫您生成這樣的適合內部使用的代碼文檔。

3.2.1 NDoc支持的標記

下面以ClassLibrary為例，介紹下NDoc支持的標記，由于為了多介紹，某些方法用了過多的標記，您可以根據自己的需要有選擇地為您的代碼添加。以下是標記與導出文件的效果對比（下文中的圖截自VSS中與此文檔同目錄的同名壓縮文件，以其中的MaxValue（int32）為主）：

<c>

從圖中可看出，添加<c>標記后，文字的顏色發生了變化，而且字體也跟代碼的字體一樣。

<c>標記指示將其內部的文本表示為代碼樣式，Inline標記，用于表示行文中的代碼片斷。

應用于其他代碼內部。

<code>

<code>標記表示將其內部的文本表示為代碼樣式，Block標記，用于表示多行的代碼塊。在其前標記內還可以加入屬性，比如：

<code [lang = "language"][escaped = "true"]>content</code>

其中：

lang = "language"

語言選擇器，表示此代碼塊僅適用于某種語言。（可選）

escaped = "true"

若content中含有XML子級，將它們視為代碼的一部分。注意：content仍然需要時格式完好的XML。（可選）

Content

將被表示為代碼塊的文本

可應用于其它Senction標記或Block標記內部。

<example>

如圖，<example>標記表示"示例"區域，Section標記，用于書寫能輔助使用者理解并快速上手的代碼示例等內容。

應用于所有類及成員。

此標記通常于<code>標記聯用。

<list>

<list>標記表示一個列表（數字列表或符號列表），或一個表格，或一個定義表。Block標記。

<list>表格可以表示為四種樣式，<list type = "bullet"|"number"|"table"|"definition">，具體見上表。

<note>

<note>標記表示一個"注意"塊。

可用于其他標記內部。

其中的參數有：

caution將顯示為"警告"，inheritinfo將顯示為"對繼承者的說明"（本例即為此），implementnotes將顯示為"對實施者的說明"。

<overloads>

<overloads>標記為"重載列表"提供文檔。

應用于屬性，方法，運算符。

此標記只需要在重載成員的第一個成員前面書寫此區域即可。此標記有兩種形式：

簡單的形式，直接在overloads里面寫文本，這些文本被處理為"重載列表"的摘要。沒有備注，示例等區域（如上圖）。

復雜的形式，在overloads內部，包含 summary, remarks, example 等標記分別表示"重載列表"頁面的摘要、備注、示例等，格式如下：

<overloads>

<summary>summary_description</summary>

[<remarks>remarks_description</remarks>]

[<example>examples_description</example>]

</overloads>

<para>

<para>標記表示一個段落，此標記亦有參數<apra lang = "language">同<code>一樣，也是語言選擇器。

此標記應用于其他標記內部，但經常用于<summary>,<remarks>及<return>等標記內部。

<param>

此標記乃用來描述方法的參數的，相信您不陌生。

<paramref>

此標記引用一個參數，將以代碼形式表示該代碼名稱（功能于<code>有點相像）。

<permission>

此標記說明訪問某成員所必需的.Net Framework安全性CodeAccessPermission。

其中：

cref = "…"

表示需要的 CodeAccessPermission 類型。書寫時，如果 CodeAccessPermission 是同一命名空間下的類型，member 可以直接寫其名稱（注意大小寫）；如果是其他命名空間的，建議您寫該 CodeAccessPermission 的完全限定名稱。C# 編譯器將檢查該 CodeAccessPermission 是否存在。在輸出的 XML 文檔文件中，C# 編譯器會自動轉換簡寫的 member 為完全限定名稱。

<preliminary>

<preliminary>標記將類型或成員標記為預發布版本，使之一直顯示在顯示框的頂部。

若標記中沒有指定內容，則以紅色顯示默認的文本: "[此文檔為預發布版本，在未來版本中有可能改變。]"

<remarks>

<remarks>標記表示對類型或成員的"備注"。<remarks>標記用于對<summary>摘要信息的補充。

<returns>

<returns>標記用于說明方法的返回值。

<seealso>

<seealso>標記用于在頁面的"請參見"區域添加一個超鏈接。

完整的形式為：

<seealso cref="member">[label]</seealso>

或

<seealso href="URL">[label]</seealso>

其中：

label

超鏈接的顯示文本。

cref = "member"

表示要鏈接到的類型(成員)。書寫時，如果要鏈接到的類型(成員)是同一命名空間(類型)中的類型(成員)，member 可以直接寫它的名稱（注意大小寫）；如果是其他命名空間(類型)的，建議您寫該類型(成員)的完全限定名稱。C# 編譯器將檢查該類型(成員)是否存在。在輸出的 XML 文檔文件中，C# 編譯器會自動轉換簡寫的 member 為完全限定名稱。

href = "URL"

一個網絡 URL 地址。

請不要將此標記包含在<remarks>標記內部。

<summary>

<summary>標記相信您很熟悉，用于對類型或成員的摘要說明。此標記是所有類型及成員最基本的說明，一般的，應為每個公共的、可見的類型/成員書寫 summary 文檔。在 Visual Studio .NET IDE 的智能感知功能及對象查看器，還有其他大多數開發工具，都會顯示 summary 信息。

<threadsafety>

<threadsafety> 標記用于說明類型在多線程環境中是否安全。

?

更多標記

更多標記請參見NDoc程序的"幫助|目錄"下的"快速教程|"裝飾"您的代碼|NDoc支持的標記"。

3.2.2 上文完整的注釋代碼

///<overloads>This method takes the most maximum number.</overloads>

????????/// <preliminary>

????????/// <para>This method is just for testing right now. It might be removed in the near future.</para>

????????/// <seealso cref="Class1.Main"/>

????????/// </preliminary>

/// <summary>

/// <c>MaxValue</c> is a method in the <c>Class1</c> class. Accept and return an "int" parameter

/// </summary>

/// <param name="intArray">所要查找最大值的int型數組</param>

/// <returns>數組的最大值</returns>

????????/// <remarks>a method in the ClassLibrary class.

????????/// The <paramref name="intArrary"/> parameter takes a "int" number.

????????/// </remarks>

???????? /// <permission cref="System.Security.PermissionSet">Everyone can access this method.</permission>

/// <example>

????????/// <note type="caution">

????????/// This sample shows how to call the MaxValue method.

????????/// </note>

/// <code>

/// class Class1

/// {

/// public static int Main()

/// {

/// return MaxValue();

/// }

/// }

/// </code>

????/// <list type="table">

????????/// <listheader>

????????/// <term><c>list</c>簡介</term>

????????/// <description>參數</description>

????????/// </listheader>

????????/// <listheader>

????????/// <term>bullet</term>

????????/// <description>bullet為符號列表，對應于HTML中的UL列表</description>

????????/// </listheader>

????????/// <listheader>

????????/// <term>number</term>

????????/// <description>number為數字列表，對應于HTML中的OL列表</description>

????????/// </listheader>

????????/// <listheader>

????????/// <term>table</term>

????????/// <description>table為表格，以表格形式表示（此處即為表格）</description>

????????/// </listheader>

????????/// <listheader>

????????/// <term>definition</term>

????????/// <description>definition為定義列表</description>

????????/// </listheader>

????????/// </list>

????????/// <note type="inheritinfo">

????????/// 注意事項

????????/// </note>

/// </example>

?

?

3.3、新建NDoc項目

3.3.1 添加整個項目

如果您使用 Visual Studio.NET 開發工具，那么最簡單的方法就是點擊工具條中的"從 Visual Studio .NET 解決方案新建 NDoc 項目..."按鈕，如下圖：

?

?

此處以test為例（注意：程序不支持中文路徑和中文名），如下圖：

?

然后，NDoc 會要求您選擇某種編譯配置(如 Debug 或 Release，或者其他您自定義的編譯配置)，這取決于您將使用哪種編譯配置下生成的程序集和 XML 文檔，如下圖：

"確定"之后，NDoc 項目設計器將自動生成一個新的 NDoc 項目，其中已包含解決方案中各個項目生成的程序集和相應的 XML 文檔（注意：請確保項目配置中已打開XML文檔輸出功能，否則NDoc的輸出效果將非常有限），如下圖：

在HtmlHelpName中填入要生成的文件名，如下圖：

同時，為了突出版權，還要給生成的文檔添加Title，標上整個項目的名稱（朗志輕量級項目管理文檔），如下圖：

按快捷鍵"Ctrl+Shift+B"或工具欄中的"生成文檔"鍵生成文檔，如下圖：

?

在與"test"同目錄下的\doc目錄下即可看到生成的文檔"test.chm"，如下圖：

則生成的Title如下圖：

您所注釋的代碼與所生成的相比如下圖：

如果您沒有使用 Visual Studio .NET，則需要手工向 NDoc 項目添加要生成代碼文檔的程序集和相應的 XML 文檔。您可以通過點擊設計器重的"添加"按鈕、從文件系統中瀏覽并選擇要添加的程序集，也可以直接從 Windows 資源管理器或"我的電腦"中、直接拖動要生成代碼文檔的程序集、到設計器中的程序集列表框中。

請確保您打開了 /doc 文檔輸出的選項，否則 NDoc 輸出的代碼文檔只能有很少的內容。

3.3.2 添加類庫（".DLL"文件）

如果創建的是類庫，也可以直接點擊"添加"按鈕直接找到目錄下的".DLL"文件添加即可，其他步驟同上。

以上兩種方法完全可以通用。

生成的文檔的效果如圖：

?

?

?

4 OVERLOAD（重載）

函數的重載允許創建同名的多個函數，這些函數可使用不同的參數類型。

例如，下面的代碼，其中包含一個MaxValue（）的函數：

class Program

????????????{

????????????????static int MaxValue(int[] intArray)

????????????????{

????????????????????int maxVal = intArray[0];

????????????????????for(int i = 1; i < intArray.Length; i++)

????????????????????{

????????????????????????if(intArray[i] > maxVal)

????????????????????????????maxVal = intArray[i];

????????????????????}

????????????????????return maxVal;

????????????????}

?

????????????????static void Main(string[] args)

????????????????{

????????????????????int[] myArray = {1,8,3,6,2,5,9,3,0,2};

????????????????????int maxVal = MaxValue(myArray);

????????????????????Console.WriteLine("The maximum value in myArray is {0}",maxValue);

????????????????????Console.ReadKey();

????????????????}

????????????}

這個函數只能用于處理int數組，現在要為不同的參數類型提供不同名稱的函數，可以把上述函數重命名為IntArrayMaxValue（），添加函數DoubleArrayMaxValue（）處理其他類型。另外，還可以在代碼中添加如下函數：

…

static double MaxValue(double[] doubleArray)

????????????????{

????????????????????double maxVal = doubleArray[0];

????????????????????for(int i = 1; i < doubleArray.Length; i++)

????????????????????{

????????????????????????if(doubleArray[i] > maxVal)

????????????????????????????maxVal = doubleArray[i];

????????????????????}

????????????????????return maxVal;

????????????????}

…

這里的區別是使用了double值。函數名稱MaxValue（）是相同的，但其簽名是不同的。用相同的名稱和簽名定義兩個函數時錯誤的，但因為這兩個函數有不同的簽名，所示是可行的。

現在有兩個版本的MaxValue（），它們的參數是int和double數組，分別返回有個int或double最大值。

這種代碼的優點是不必顯示指定要使用哪個函數。只需提供一個數組參數，就可以根據使用的參數類型執行相應的函數。

此時，應該注意VS中的IntelliSense的另一個功能。如果在應用程序中有上述兩個函數，而且要在Main（）中輸入函數名稱，VS就可以顯示出可用的重載函數。如果輸入下面的代碼：

double result = MaxValue(

VS提供了MaxValue（）兩個版本的信息，使用上下箭頭鍵可以在它們之間滾動，如下圖：

在重載函數時，應包括函數簽名的所有方面。例如有兩個不同的函數，它們分別帶有值參數和引用參數：

static void showDouble(ref int val)

????????????????{

……

?

????????????????}

????????????????static void showDouble(int val)

????????????????{

……

????????????????}

選擇使用哪個版本純粹時根據函數調用是否包含ref關鍵字來確定。下面的代碼時調用引用版本：

showDouble(ref val);

下面的代碼是調用值版本：

showDouble(val);

另外，函數還可以根據參數的個數等來區分。

posted on 2007-11-29 18:47?lexus 閱讀(...) 評論(...) 編輯 收藏

轉載于:https://www.cnblogs.com/lexus/archive/2007/11/29/977307.html

總結

以上是生活随笔為你收集整理的NDoc1.3.1使用手册的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。