當(dāng)前位置：首頁 > 编程资源 > 编程问答 >内容正文

编程问答

NDoc1.3.1使用手册

發(fā)布時(shí)間：2023/12/20 编程问答 30 豆豆

生活随笔收集整理的這篇文章主要介紹了 NDoc1.3.1使用手册小編覺得挺不錯(cuò)的,現(xiàn)在分享給大家,幫大家做個(gè)參考.

NDoc1.3.1使用手冊(cè)

2、安裝（for VS2003）

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

點(diǎn)擊"下一步"：

選擇要安裝的路徑，點(diǎn)擊"下一步"，如下圖：

選擇"同意"，點(diǎn)擊"下一步"繼續(xù)，再點(diǎn)"下一步"進(jìn)行安裝，如下圖：

點(diǎn)擊"關(guān)閉"完成安裝，如下圖：

3、使用

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

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

3.1 配置您的C#項(xiàng)目

首先，您應(yīng)該確認(rèn)，您已經(jīng)打開了 C# 項(xiàng)目的 /doc 開關(guān)，當(dāng) Visual Studio .NET 編譯時(shí)，每次都會(huì)生成相應(yīng)的 XML 文檔。

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

此處以"Example069-繪制藝術(shù)圖案（1）"為例，打開"項(xiàng)目|屬性"對(duì)話框，如下圖：

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

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

點(diǎn)擊"確定"。現(xiàn)在，每次使用 VS.NET 編譯您的程序集，都會(huì)自動(dòng)從源代碼中提取所有的 XML 注釋，生成 XML 文檔文件（但是每個(gè)不同的項(xiàng)目都得設(shè)置一次），如下圖：

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

3.2 "裝飾"您的代碼

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

一般而言的最低要求，對(duì)于每一個(gè)公共類型，應(yīng)該給它的所有公共的和受保護(hù)的成員添加 <summary> 注釋，以描述該成員表示什么意義或者會(huì)做些什么動(dòng)作。

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

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

如果在下面的選項(xiàng)中找不到"任務(wù)列表"，可以點(diǎn)擊"視圖|其它窗口|任務(wù)列表"打開，如下圖：

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

比如如下的代碼:

public class MyClass() {

public MyClass( string s ) { }

}

把光標(biāo)移動(dòng)到 MyClass 構(gòu)造函數(shù)的上面一空行，敲 '/' 鍵三次，VS.NET 自動(dòng)創(chuàng)建一個(gè) summary XML 文檔塊（在VS2005中更可以使用GhostDoc更方便地生成注釋，詳細(xì)內(nèi)容請(qǐng)見《[技術(shù)文檔]GhostDoc2.1.1使用手冊(cè)》）:

public class MyClass() {

/// <summary>

///

/// </summary>

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

public MyClass( string s ) { }

}

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

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

3.2.1 NDoc支持的標(biāo)記

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

<c>

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

<c>標(biāo)記指示將其內(nèi)部的文本表示為代碼樣式，Inline標(biāo)記，用于表示行文中的代碼片斷。

應(yīng)用于其他代碼內(nèi)部。

<code>

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

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

其中：

lang = "language"

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

escaped = "true"

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

Content

將被表示為代碼塊的文本

可應(yīng)用于其它Senction標(biāo)記或Block標(biāo)記內(nèi)部。

<example>

如圖，<example>標(biāo)記表示"示例"區(qū)域，Section標(biāo)記，用于書寫能輔助使用者理解并快速上手的代碼示例等內(nèi)容。

應(yīng)用于所有類及成員。

此標(biāo)記通常于<code>標(biāo)記聯(lián)用。

<list>

<list>標(biāo)記表示一個(gè)列表（數(shù)字列表或符號(hào)列表），或一個(gè)表格，或一個(gè)定義表。Block標(biāo)記。

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

<note>

<note>標(biāo)記表示一個(gè)"注意"塊。

可用于其他標(biāo)記內(nèi)部。

其中的參數(shù)有：

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

<overloads>

<overloads>標(biāo)記為"重載列表"提供文檔。

應(yīng)用于屬性，方法，運(yùn)算符。

此標(biāo)記只需要在重載成員的第一個(gè)成員前面書寫此區(qū)域即可。此標(biāo)記有兩種形式：

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

復(fù)雜的形式，在overloads內(nèi)部，包含 summary, remarks, example 等標(biāo)記分別表示"重載列表"頁面的摘要、備注、示例等，格式如下：

<summary>summary_description</summary>

[<remarks>remarks_description</remarks>]

[<example>examples_description</example>]

</overloads>

<para>

<para>標(biāo)記表示一個(gè)段落，此標(biāo)記亦有參數(shù)<apra lang = "language">同<code>一樣，也是語言選擇器。

此標(biāo)記應(yīng)用于其他標(biāo)記內(nèi)部，但經(jīng)常用于<summary>,<remarks>及<return>等標(biāo)記內(nèi)部。

<param>

此標(biāo)記乃用來描述方法的參數(shù)的，相信您不陌生。

<paramref>

此標(biāo)記引用一個(gè)參數(shù)，將以代碼形式表示該代碼名稱（功能于<code>有點(diǎn)相像）。

<permission>

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

其中：

cref = "…"

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

<preliminary>

<preliminary>標(biāo)記將類型或成員標(biāo)記為預(yù)發(fā)布版本，使之一直顯示在顯示框的頂部。

若標(biāo)記中沒有指定內(nèi)容，則以紅色顯示默認(rèn)的文本: "[此文檔為預(yù)發(fā)布版本，在未來版本中有可能改變。]"

<remarks>

<remarks>標(biāo)記表示對(duì)類型或成員的"備注"。<remarks>標(biāo)記用于對(duì)<summary>摘要信息的補(bǔ)充。

<returns>

<returns>標(biāo)記用于說明方法的返回值。

<seealso>

<seealso>標(biāo)記用于在頁面的"請(qǐng)參見"區(qū)域添加一個(gè)超鏈接。

完整的形式為：

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

或

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

其中：

label

超鏈接的顯示文本。

cref = "member"

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

href = "URL"

一個(gè)網(wǎng)絡(luò) URL 地址。

請(qǐng)不要將此標(biāo)記包含在<remarks>標(biāo)記內(nèi)部。

<summary>

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

<threadsafety>

<threadsafety> 標(biāo)記用于說明類型在多線程環(huán)境中是否安全。

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型數(shù)組</param>

/// <returns>數(shù)組的最大值</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>簡(jiǎn)介</term>

????????/// <description>參數(shù)</description>

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

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

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

????????/// <description>bullet為符號(hào)列表，對(duì)應(yīng)于HTML中的UL列表</description>

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

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

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

????????/// <description>number為數(shù)字列表，對(duì)應(yīng)于HTML中的OL列表</description>

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

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

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

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

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

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

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

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

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

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

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

????????/// 注意事項(xiàng)

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

/// </example>

3.3、新建NDoc項(xiàng)目

3.3.1 添加整個(gè)項(xiàng)目

如果您使用 Visual Studio.NET 開發(fā)工具，那么最簡(jiǎn)單的方法就是點(diǎn)擊工具條中的"從 Visual Studio .NET 解決方案新建 NDoc 項(xiàng)目..."按鈕，如下圖：

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

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

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

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

同時(shí)，為了突出版權(quán)，還要給生成的文檔添加Title，標(biāo)上整個(gè)項(xiàng)目的名稱（朗志輕量級(jí)項(xiàng)目管理文檔），如下圖：

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

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

則生成的Title如下圖：

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

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

請(qǐng)確保您打開了 /doc 文檔輸出的選項(xiàng)，否則 NDoc 輸出的代碼文檔只能有很少的內(nèi)容。

3.3.2 添加類庫(kù)（".DLL"文件）

如果創(chuàng)建的是類庫(kù)，也可以直接點(diǎn)擊"添加"按鈕直接找到目錄下的".DLL"文件添加即可，其他步驟同上。

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

生成的文檔的效果如圖：

4 OVERLOAD（重載）

函數(shù)的重載允許創(chuàng)建同名的多個(gè)函數(shù)，這些函數(shù)可使用不同的參數(shù)類型。

例如，下面的代碼，其中包含一個(gè)MaxValue（）的函數(shù)：

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();

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

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

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

…

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;

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

…

這里的區(qū)別是使用了double值。函數(shù)名稱MaxValue（）是相同的，但其簽名是不同的。用相同的名稱和簽名定義兩個(gè)函數(shù)時(shí)錯(cuò)誤的，但因?yàn)檫@兩個(gè)函數(shù)有不同的簽名，所示是可行的。

現(xiàn)在有兩個(gè)版本的MaxValue（），它們的參數(shù)是int和double數(shù)組，分別返回有個(gè)int或double最大值。

這種代碼的優(yōu)點(diǎn)是不必顯示指定要使用哪個(gè)函數(shù)。只需提供一個(gè)數(shù)組參數(shù)，就可以根據(jù)使用的參數(shù)類型執(zhí)行相應(yīng)的函數(shù)。

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

double result = MaxValue(

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

在重載函數(shù)時(shí)，應(yīng)包括函數(shù)簽名的所有方面。例如有兩個(gè)不同的函數(shù)，它們分別帶有值參數(shù)和引用參數(shù)：

static void showDouble(ref int val)

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

……

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

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

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

……

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

選擇使用哪個(gè)版本純粹時(shí)根據(jù)函數(shù)調(diào)用是否包含ref關(guān)鍵字來確定。下面的代碼時(shí)調(diào)用引用版本：

showDouble(ref val);

下面的代碼是調(diào)用值版本：

showDouble(val);

另外，函數(shù)還可以根據(jù)參數(shù)的個(gè)數(shù)等來區(qū)分。

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

轉(zhuǎn)載于:https://www.cnblogs.com/lexus/archive/2007/11/29/977307.html

總結(jié)

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

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。

使用手册

上一篇： IGARSS2019-项目实战总结-ke
下一篇： mysql odbc连接 mdb_jav

编程问答

NDoc1.3.1使用手册

目錄

2、安裝（for VS2003）

3、使用

3.1 配置您的C#項(xiàng)目

3.2 "裝飾"您的代碼

3.2.1 NDoc支持的標(biāo)記

<c>

<code>

<example>

<list>

<note>

<overloads>

<para>

<param>

<paramref>

<permission>

<preliminary>

<remarks>

<returns>

<seealso>

<summary>

<threadsafety>

更多標(biāo)記

3.2.2 上文完整的注釋代碼

3.3、新建NDoc項(xiàng)目

3.3.1 添加整個(gè)項(xiàng)目

3.3.2 添加類庫(kù)（".DLL"文件）

4 OVERLOAD（重載）

總結(jié)