• 歡迎使用 NDoc
  • What's New?
  • 已知問(wèn)題
• 快速教程
  • 配置您的 C# 項(xiàng)目
  • “裝飾”您的代碼
    • NDoc 支持的標(biāo)記
    • NDoc 支持的屬性 (Attribute)
  • 新建 NDoc 項(xiàng)目
• NDoc 設(shè)計(jì)器
  • 選項(xiàng)
• NDoc 命令行工具
  • 使用 NDoc 命令行自動(dòng)生成代碼文檔
• NDoc 文檔引擎
  • VS.NET 文檔引擎
    • 指向其他文檔集合的 XLinks
    • 與 Visual Studio .NET IDE 的集成
    • Microsoft Help 2 部署
  • MSDN 文檔引擎
  • MSDN 2003 文檔引擎
  • XML 文檔引擎
  • JavaDoc 文檔引擎
  • Linear HTML 文檔引擎
  • LaTeX 文檔引擎
• NDoc 支持的標(biāo)記
  • 標(biāo)記用法
  • <c>
  • <code>
  • <event>
  • <example>
  • <exception>
  • <exclude>
  • <include>
  • <list>
  • <note>
  • <overloads>
  • <para>
  • <param>
  • <paramref>
  • <permission>
  • <preliminary>
  • <remarks>
  • <returns>
  • <see>
  • <seealso>
  • <summary>
  • <threadsafety>
  • <value>
• 定義您自己的標(biāo)記
  • 可用 Section 的列表
• NDoc 開(kāi)發(fā)者參考
• 加入 NDoc 開(kāi)發(fā)
• 支持資源

關(guān)于 NDoc
　NDoc 可以將 C#.NET 編譯生成的程序集和對(duì)應(yīng)的 /doc XML 文檔，自動(dòng)轉(zhuǎn)換成如 .NET Framework SDK 類(lèi)庫(kù)文檔或者 MSDN Library 在線(xiàn) .NET 類(lèi)庫(kù)文檔形式的代碼文檔，讓您快速擁有專(zhuān)業(yè)級(jí)的類(lèi)庫(kù)API 文檔。(VB.NET 通過(guò)第三方插件如 VBCommenter 的支持，也可以生成 XML 文檔。)

　NDoc 代碼文檔的樣式包括 HTML Help 1 (即 *.CHM 格式)，Microsoft Help 2 (即以形如 ms-help://... 的 URI 地址訪(fǎng)問(wèn)的文檔)，以及 MSDN 在線(xiàn)網(wǎng)頁(yè)樣式的 .NET Framework 類(lèi)庫(kù)文檔。

NDoc 為開(kāi)放源代碼項(xiàng)目，采用 GNU General Public Licence 授權(quán)協(xié)議（除非您的軟件/項(xiàng)目也采用 GPL 協(xié)議開(kāi)放源代碼，否則您不能在您的軟件/項(xiàng)目中使用 NDoc 源代碼中的任何部分）。更多的授權(quán)問(wèn)題，請(qǐng)參見(jiàn) GNU FAQ。

感謝您使用我們的軟件，也期待著您的參與（建議、BUG 反饋、代碼貢獻(xiàn)）！

使用 NDoc 之前
請(qǐng)閱讀 GNU General Public Licence 和 GNU FAQ。

請(qǐng)閱讀 已知問(wèn)題。

請(qǐng)閱讀 必要的幫助文件編譯器。

NDoc 各本地化版本
　英文版: NDoc in English
　簡(jiǎn)體中文版: NDoc in Simplified Chinese
　德文版: NDoc in German
　日文版: NDoc in Japanese
　(此列表可能并不完整。歡迎大家給我發(fā)送更多關(guān)于 NDoc 的本地化版本的網(wǎng)址！)

關(guān)于中文版
　此 NDoc 1.3 (中文版) 由 破寶(percyboy) 翻譯，遵循 GPL 協(xié)議的要求發(fā)布源代碼。有關(guān)中文版的翻譯問(wèn)題和 bug 等，都可以通過(guò)我的博客和我聯(lián)系。

NDoc 1.3 - What's new?
　NDoc 1.3 包含了大量更新和改進(jìn)，也修復(fù)了許多 bug。

亮點(diǎn)
　NDoc 1.3 包含了許多新功能:

• 完全重寫(xiě)了 Microsoft Help 2 文檔引擎，即 "VS.NET 2003 文檔引擎"。
• 支持更多新的注釋標(biāo)記，如 preliminary, threadsafety 和 exclude。
• 支持 ObsoleteAttribute 和 FlagsAttribute 屬性。
• NDoc 1.3 改進(jìn)了可擴(kuò)展性，允許您定義自己的注釋標(biāo)記，并控制它們的顯示樣式。
• 用戶(hù)界面更加友好。
• 程序集的解析及文檔制作過(guò)程，在性能上有了大的提高。
• 與 MSDN 各幫助主題更好的共存。

VS.NET 2003 文檔引擎
　新的 VS.NET 2003 文檔引擎用于制作 Microsoft Help 2 形式的文檔，完全按照 Microsoft 的說(shuō)明，在每頁(yè)頭部都加入了特定的 XML 數(shù)據(jù)島，從而和 Visual Studio .NET 2003 合并文檔集合更好的兼容，和 Visual Studio .NET IDE 更好的集成(比如更好的支持“動(dòng)態(tài)幫助”功能等)。

新的文檔引擎可以制作出和最新 Microsoft 文檔格式更為接近的文檔，比如新增的語(yǔ)言篩選器等功能。

更多的細(xì)節(jié)請(qǐng)參看 VS.NET 2003 文檔引擎。

性能
　所有文檔引擎的性能都有很大程度的提高。

• NDoc 中間 XML 數(shù)據(jù)文件的制作過(guò)程有了相當(dāng)?shù)奶崴?#xff0c;現(xiàn)在這個(gè)過(guò)程在整個(gè)文檔生成過(guò)程中所占的時(shí)間比例已經(jīng)很小了。
• 頁(yè)面制作的時(shí)間也減少了 20% ~ 50%。
• 內(nèi)存占用顯著降低了。
• 命名空間層次結(jié)構(gòu)頁(yè)面的制作過(guò)程，得到了改進(jìn)，不再擔(dān)心性能或穩(wěn)定性問(wèn)題了。因此，文檔引擎總是制作命名空間層次結(jié)構(gòu)頁(yè)。

程序集加載
　程序集的加載方法有了不少改進(jìn)。

• 程序集改變時(shí)，GUI 程序不需要重新啟動(dòng)就能反映更新。
• 大多數(shù)程序集可以從網(wǎng)絡(luò)共享地址加載。但是，因?yàn)?.NET Framework 的安全限制，由托管 C++ 生成的程序集必須在本地磁盤(pán)中，不能從網(wǎng)絡(luò)共享地址中正常加載。
• 程序集的解析得到了改進(jìn)，現(xiàn)在已經(jīng)極少出錯(cuò)了。

國(guó)際化
　NDoc 現(xiàn)在可以正常處理程序集及代碼注釋中包含的非英文字符。除 MSDN 文檔引擎(HTML Help 1 格式)之外，其他文檔引擎都完全支持 Unicode (UTF-8)字符。受 HTML Help 1 的局限，MSDN 文檔引擎不支持混合字符集，這是我們所無(wú)法控制的。

注意，盡管 NDoc 支持多種字符集，但 NDoc 生成的代碼文檔的各個(gè)標(biāo)題、及 NDoc 的界面、提示消息等文本，在 NDoc 1.3 中還未實(shí)現(xiàn)多語(yǔ)言顯示。

NDoc 并行運(yùn)行能力
　多個(gè) NDoc 實(shí)例現(xiàn)在可以同時(shí)并行運(yùn)行。先前的文件鎖定等問(wèn)題已經(jīng)得到解決。

用戶(hù)界面

• 對(duì)拖放操作的支持。新版本中，您可以直接將程序集從資源管理器中拖曳到 NDoc GUI 的程序集列表中。
• 錯(cuò)誤處理。新版本的錯(cuò)誤處理得到了顯著的改進(jìn)。
• 幫助編譯器消息。幫助編譯器的消息被記入 log。如果出錯(cuò)，錯(cuò)誤消息被顯示出來(lái)。
• 屬性網(wǎng)格。屬性網(wǎng)格有了不少加強(qiáng)。
• 能處理程序集加載錯(cuò)誤。
• 對(duì)沒(méi)有 XML 文檔的程序集，也能為輸出簡(jiǎn)單的代碼文檔。
• 對(duì)相對(duì)路徑的支持。一般都是相對(duì)于 NDoc 項(xiàng)目文件。

XML 文檔標(biāo)記
　新標(biāo)記

增強(qiáng)的標(biāo)記

配置
　新配置項(xiàng)
　NDoc 1.3 加入了下面的通用配置項(xiàng):

刪除的配置項(xiàng)
　NDoc 1.3 刪除了下面的配置項(xiàng):

MSDN 文檔引擎
　新配置項(xiàng)
　NDoc 1.3 為 MSDN 文檔引擎加入了下面的配置項(xiàng):

刪除的配置項(xiàng)
　NDoc 1.3 刪除了下面的配置項(xiàng):

改進(jìn)的超鏈接邏輯
　<see> 將形成一個(gè)指向另一個(gè)類(lèi)型/成員的文檔的鏈接。在 NDoc 1.3 中，如果一個(gè) HTML 頁(yè)中出現(xiàn)了多個(gè)指向同一個(gè)類(lèi)型/成員的文檔的 <see>，則只轉(zhuǎn)換第一個(gè)為超鏈接，其余的不表示為超鏈接、只顯示為粗體。這將使頁(yè)面不至于太雜亂。

HTML Help 1 目錄樹(shù)中的圖標(biāo)
　目錄樹(shù)中，不再出現(xiàn)問(wèn)號(hào)(?)圖標(biāo)。如果沒(méi)有指定，顯示為空白頁(yè)圖標(biāo)。

運(yùn)算符和類(lèi)型轉(zhuǎn)換
　NDoc 1.3 修復(fù)了對(duì)運(yùn)算符和類(lèi)型轉(zhuǎn)換的處理 bug，頁(yè)面格式也更接近 .NET Framework SDK 類(lèi)庫(kù)文檔。

特別的屬性
　ObsoleteAttribute
　MSDN, MSDN 2003, VS.NET 2003 文檔引擎，將自動(dòng)為具有 ObsoleteAttribute 屬性的類(lèi)型/成員添加紅色的提示文本。

• 在命名空間列表及類(lèi)型的成員列表中，將為它們顯示紅色的“已過(guò)時(shí)。”
• 在類(lèi)型概述頁(yè)/成員頁(yè)中，將為它們添加紅色的“注意：此成員現(xiàn)已過(guò)時(shí)。”

FlagsAttribute
　如果枚舉具有 FlagsAttribute 屬性，MSDN, MSDN 2003, VS.NET 2003 文檔引擎將自動(dòng)為它們添加如下的文本:

“此枚舉具有允許按位組合其成員值的 FlagsAttribute 屬性。”

NDoc 1.3 的已知問(wèn)題和限制

開(kāi)始之前，您需要準(zhǔn)備以下工具，它們可以從網(wǎng)絡(luò)中獲得。

HTML Help 1 編譯器
　HTML Help 1 文件，也就是 CHM 文件，是很常見(jiàn)的應(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 編譯器。

Microsoft Help 2 編譯器
　Microsoft Help 2 是 Microsoft 從 Visual Studio .NET 2002 開(kāi)始使用的、一種新的幫助文檔格式。

如果您準(zhǔn)備創(chuàng)建 Microsoft Help 2 (*.HxS)文件，請(qǐng)下載并安裝 Visual Studio Help Integration Kit (VSHIK)。此工具包已包含所必需的 Microsoft Help 2 編譯器。

Latex 編譯器
　如果您準(zhǔn)備使用 LaTeX 文檔引擎創(chuàng)建 dvi 或 pdf 文件，您需要下載并安裝一個(gè) LaTeX 系統(tǒng)，比如免費(fèi)的 MikTeX。

其他工具
　H2Reg
　向客戶(hù)機(jī)部署 Microsoft Help 2 幫助文檔，不像 HTML Help 1 那樣簡(jiǎn)單(僅復(fù)制即可完成)。VSHIK 工具包介紹了 如何向客戶(hù)機(jī)部署 Microsoft Help 2 幫助文檔的詳細(xì)步驟和指導(dǎo)。

另外一種方案是采用共享軟件 H2Reg utility (開(kāi)發(fā)商: helpware.net)。

H2Reg 許可您將它包含進(jìn)部署安裝包中，它可以用來(lái)注冊(cè) Microsoft Help 2 命名空間和幫助標(biāo)題等。H2Reg 使用 INI 文件描述要部署的幫助文檔結(jié)構(gòu)。NDoc 創(chuàng)建符合 H2Reg 需要的 INI 文件，指示它進(jìn)行命名空間的注冊(cè)工作。

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

如果沒(méi)有特殊情況，請(qǐng)讓項(xiàng)目輸出的程序集名稱(chē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)化您的操作。

打開(kāi)項(xiàng)目的“屬性”對(duì)話(huà)框，

找到程序集名稱(chēng)

設(shè)置 XML 文檔文件為程序集名稱(chēng)(擴(kuò)展名改為 xml)。別忘了設(shè)置此項(xiàng)之前，選擇“所有配置”，讓 Debug 或 Release 配置下，都自動(dòng)生成 XML 文檔。

設(shè)置 XML 文檔文件配置

現(xiàn)在，每次使用 VS.NET 編譯您的程序集，都會(huì)自動(dòng)從源代碼中提取所有的 XML 注釋，生成 XML 文檔文件。

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

　The more, the better
　您在代碼中書(shū)寫(xiě)的 XML 注釋越多，最終生成的代碼文檔越專(zhuān)業(yè)。程序集的使用者越能從中獲得幫助。

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

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

比如如下的代碼:

把光標(biāo)移動(dòng)到 MyClass 構(gòu)造函數(shù)的上面一空行，敲 '/' 鍵三次，VS.NET 自動(dòng)創(chuàng)建一個(gè) summary XML 文檔塊:

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

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

NDoc 內(nèi)置的 MSDN, MSDN 2003, VS.NET 文檔引擎，支持 C# 程序員參考中的所有 XML 文檔注釋標(biāo)記。

NDoc 支持?jǐn)U充的標(biāo)記和語(yǔ)法。某些標(biāo)記只能用于特定的類(lèi)型（類(lèi)，結(jié)構(gòu)，委托，接口，枚舉）或成員（字段，屬性，方法，事件等），請(qǐng)參見(jiàn)標(biāo)記用法。

NDoc 將標(biāo)記區(qū)分為三類(lèi): Section 標(biāo)記，Block 標(biāo)記，Inline 標(biāo)記。

Section 標(biāo)記
　Section 標(biāo)記用于定義不同的代碼文檔的區(qū)域。它們都是頂級(jí)標(biāo)記，Block 標(biāo)記、Inline 標(biāo)記都應(yīng)包含在某個(gè) Section 標(biāo)記的內(nèi)部。（除非自定義了擴(kuò)展 XSLT 轉(zhuǎn)換，否則，在 Section 標(biāo)記外部的 Block 標(biāo)記或 Inline 標(biāo)記都被忽略。）

Block 標(biāo)記
　Block 標(biāo)記用于 Section 標(biāo)記的內(nèi)部，它們將顯示在單獨(dú)的行中。

Inline 標(biāo)記
Inline 標(biāo)記可以用于其他 Section 標(biāo)記或 Block 標(biāo)記內(nèi)部，它們將和前后的文本顯示在同一行中。

NDoc 中的 MSDN 文檔引擎和 VS.NET 文檔引擎使用了一些 屬性 來(lái)控制代碼文檔中一些特殊樣式。

如果類(lèi)型或成員具有以下屬性，NDoc 將顯示相應(yīng)的特殊樣式，使文檔看起來(lái)更加專(zhuān)業(yè)。

新建 NDoc 項(xiàng)目和添加程序集
　如果您使用 Visual Studio.NET 開(kāi)發(fā)工具，那么最簡(jiǎn)單的方法就是點(diǎn)擊工具條中的“從 Visual Studio .NET 解決方案新建 NDoc 項(xiàng)目...”按鈕。

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

　編譯配置選擇對(duì)話(huà)框

“確定”之后，NDoc 項(xiàng)目設(shè)計(jì)器將自動(dòng)生成一個(gè)新的 NDoc 項(xiàng)目，其中已包含解決方案中各個(gè)項(xiàng)目生成的程序集和相應(yīng)的 XML 文檔。

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

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

選擇文檔引擎
　NDoc 內(nèi)置了若干文檔引擎，它們可以用于生成不同風(fēng)格、樣式、格式的代碼文檔。每種文檔引擎都定義了它自己的排版、格式，以及要輸出的內(nèi)容。

最受歡迎的兩種文檔引擎是 MSDN 和 VS.NET 2003。它們都生成類(lèi)似 .NET Framework SDK 類(lèi)庫(kù)文檔樣式的代碼文檔，不同的是前者最終編譯成 HTML Help 1 （即 *.CHM）格式的整合文件，后者最終編譯成 Microsoft Help 2 (即以形如 ms-help://... 的 URI 地址訪(fǎng)問(wèn)的文檔)格式的形式。

NDoc 1.3 中，新增了 MSDN 2003 文檔引擎，在保留 MSDN 文檔引擎的特點(diǎn)之外，向接近 .NET Framework SDK 類(lèi)庫(kù)文檔的方向又前進(jìn)了一大步：加入了語(yǔ)言選擇器等特色功能。

NDoc 文檔引擎

所有的文檔引擎都共享一些配置項(xiàng)，比如要輸出哪些類(lèi)型/不輸出哪些類(lèi)型等；每種文檔引擎都會(huì)有一些額外的配置項(xiàng)，用于特定的配置。

更多的細(xì)節(jié)請(qǐng)參看文檔引擎。

生成代碼文檔
　選擇好文檔引擎，并做好相應(yīng)的配置。您就可以點(diǎn)擊“生成”按鈕讓 NDoc 創(chuàng)建您需要的代碼文檔了。設(shè)計(jì)器下方的“輸出”窗口中將顯示文檔制作中的消息，狀態(tài)條上的進(jìn)度條指示生成的整體進(jìn)度。

NDoc 生成進(jìn)度

查看文檔
　生成成功后，您可以點(diǎn)擊“查看文檔”按鈕查看生成的代碼文檔。

概述
　NDoc 項(xiàng)目文件保存了您要輸出代碼文檔的程序集、相應(yīng)的 XML 文檔、選用的文檔引擎及配置參數(shù)等信息。

NDoc 項(xiàng)目設(shè)計(jì)器

新建 NDoc 項(xiàng)目的工作可以很簡(jiǎn)單：選擇要輸出代碼文檔的程序集、相應(yīng)的 XML 文檔、選擇一個(gè)文檔引擎并做好配置參數(shù)。

命名空間摘要
　標(biāo)準(zhǔn)的 C# 注釋 XML 文檔中，沒(méi)有提供任何標(biāo)記為命名空間提供“summary”文檔。NDoc 提供了兩種途徑允許您為命名空間提供“summary”文檔。一種是通過(guò)在您的代碼加入特定的類(lèi)，并對(duì) NDoc 文檔引擎作相應(yīng)配置（請(qǐng)參見(jiàn) NDoc 文檔引擎 中關(guān)于 UseNamespaceDocSummaries 配置項(xiàng)的說(shuō)明）。另一種途徑是通過(guò)項(xiàng)目設(shè)計(jì)器指定各命名空間的摘要文檔。

在項(xiàng)目設(shè)計(jì)器中，單擊“命名空間摘要”按鈕，在彈出的“編輯命名空間摘要”對(duì)話(huà)框中，給每個(gè)命名空間填寫(xiě)摘要文檔。

這些摘要文檔將包含在最終生成的代碼文檔中。

編輯命名空間摘要對(duì)話(huà)框

文檔引擎配置
各種文檔引擎間共享一些基本配置項(xiàng)，比如輸出過(guò)濾(是否輸出 private 成員等)，缺少文檔時(shí)的處理對(duì)策等；各文檔引擎又包含自己的某些特殊配置項(xiàng)。這些配置項(xiàng)都可以通過(guò)項(xiàng)目設(shè)計(jì)器查看、更改，并保存到項(xiàng)目文件中。

設(shè)計(jì)器中配置項(xiàng)以類(lèi)別排列，并且，選中某一配置項(xiàng)時(shí)會(huì)顯示一小段提示文本，說(shuō)明該配置項(xiàng)的用途和用法。這些都將幫助您快速掌握這些文檔引擎的使用方法。

關(guān)于完整的文檔引擎列表，及其配置項(xiàng)，請(qǐng)參見(jiàn) NDoc 文檔引擎。

選項(xiàng)

概述
　NDoc 不僅提供了 GUI 的界面，也同時(shí)提供了命令行工具(NDocConsole.exe)，為和其他開(kāi)發(fā)工具集成提供了方便。
　
　語(yǔ)法
　NDoc 命令行使用簡(jiǎn)單的“name-value 對(duì)”語(yǔ)法來(lái)指定相應(yīng)的配置項(xiàng)。每個(gè)選項(xiàng)前用一個(gè)短線(xiàn)，如：-name=value，短線(xiàn)和等號(hào)周?chē)灰锌崭瘛Ｏ旅嬲Z(yǔ)法敘述中，中括號(hào)的部分是可選的。路徑中如果包含有空格，則需要用引號(hào)(")括起來(lái)。
　用法 1

?

注釋:

• 程序集: 要生成文檔的完整路徑。
• XML文檔: 對(duì)應(yīng)的 XML 文檔（C# 編譯器 /doc 輸出的 XML 文檔）。
  缺省時(shí)，將自動(dòng)查找和程序集相同路徑、相同名稱(chēng)，僅擴(kuò)展名不同(.xml)的 XML 文件代替。
• referencepath: 引用的第三方 dll 的搜索路徑。
• namespacesummaries: 要使用的 命名空間摘要 XML 文檔 的完整路徑。
• documenter: 要使用的文檔引擎的名稱(chēng)。注意此項(xiàng)區(qū)分大小寫(xiě)。
  缺省時(shí)，將使用 MSDN 文檔引擎。
• 引擎參數(shù): 文檔引擎的配置參數(shù)名稱(chēng)，注意此項(xiàng)區(qū)分大小寫(xiě)。
• 值: 給引擎參數(shù)設(shè)置的值。
• verbose: 顯示文檔生成進(jìn)度的輸出消息。

用法 2

注釋:

• recurse: 您可以將要生成文檔的程序集和它們對(duì)應(yīng)的 XML 文檔放在同一文件夾中（注意：XML 文檔的文件名應(yīng)和對(duì)應(yīng)的程序集文件名相同，僅擴(kuò)展名不同），將此文件夾指定給此參數(shù)，NDoc 將自動(dòng)查找程序集和 XML 文檔。這是一種比較簡(jiǎn)單的用法。
• 最大讀取深度: 在 recurse 參數(shù)指定的文件夾中的讀取深度。
• referencepath: 引用的第三方 dll 的搜索路徑。
• namespacesummaries要使用的 命名空間摘要 XML 文檔 的完整路徑。
• documenter: 要使用的文檔引擎的名稱(chēng)。注意此項(xiàng)區(qū)分大小寫(xiě)。
  缺省時(shí)，將使用 MSDN 文檔引擎。
• 引擎參數(shù): 文檔引擎的配置參數(shù)名稱(chēng)，注意此項(xiàng)區(qū)分大小寫(xiě)。
• 值: 給引擎參數(shù)設(shè)置的值。
• verbose: 顯示文檔生成進(jìn)度的輸出消息。

用法 3
　NDocConsole [-documenter=文檔引擎] -project=NDOC項(xiàng)目文件 [-verbose]
　
　注釋:

• documenter: 要使用的文檔引擎的名稱(chēng)。注意此項(xiàng)區(qū)分大小寫(xiě)。
  缺省時(shí)，將使用 MSDN 文檔引擎。
• project: 您可以使用 NDoc GUI 界面保存一個(gè) NDoc 項(xiàng)目文件，然后設(shè)置給此參數(shù)。
• verbose: 顯示文檔生成進(jìn)度的輸出消息。

用法 4
　NDocConsole [-help] [文檔引擎 [引擎參數(shù)]]
　
　where:

• help: 顯示命令行幫助信息。
  如果文檔引擎參數(shù)沒(méi)有指定，顯示 NDoc 命令行的基本語(yǔ)法。
• 文檔引擎: 顯示此文檔引擎的幫助信息（如：可用的配置參數(shù)項(xiàng)等）。注意此項(xiàng)區(qū)分大小寫(xiě)。
  如果引擎參數(shù)沒(méi)有指定，顯示此文檔引擎可用的配置參數(shù)列表。
• 引擎參數(shù): 顯示文檔引擎的某配置參數(shù)的信息，如描述、默認(rèn)值。若參數(shù)為枚舉類(lèi)型，還會(huì)列出可用的枚舉值（使用時(shí)注意區(qū)分大小寫(xiě)）。

可用的文檔引擎
　NDoc 1.3 自帶的文檔引擎包括: JavaDoc, LaTeX, LinearHtml, MSDN, MSDN_2003, VS.NET_2003, 以及 XML。

您可以使用 NDocConsole -help 看到實(shí)際的列表。

命名空間摘要 XML 文檔的語(yǔ)法

配置 NAnt(暫無(wú))

配置 VS.NET
　您可以利用 VS.NET 中提供的生成事件功能，將 NDoc 配置為在每次代碼編譯完成后、自動(dòng)生成相應(yīng)的代碼文檔。同時(shí) NDoc 代碼文檔生成將花費(fèi)不少時(shí)間，因此建議您只在 Release 配置狀態(tài)(或其他自定義的配置狀態(tài))時(shí)允許自動(dòng)文檔生成。

而 C# 項(xiàng)目的生成事件并不區(qū)分各種配置狀態(tài)(如 Debug 或 Release )，因此需要在生成事件的腳本中添加對(duì)配置狀態(tài)(VS.NET 內(nèi)置的編譯變量)的判斷，如：

if $(ConfigurationName) == Release
　因?yàn)橹苯釉谏墒录翱谥姓_書(shū)寫(xiě) NDoc 命令行命令及相關(guān)參數(shù)、很困難也很容易出現(xiàn)錯(cuò)誤，因此您可以將命令寫(xiě)在一個(gè)批處理 .bat 文件中，而在項(xiàng)目的生成后事件中引用這個(gè)批處理文件(如下圖)，這樣比較容易書(shū)寫(xiě)和維護(hù)。

Calling a batch file from the post-build event

一個(gè)解決方案中有多個(gè)項(xiàng)目時(shí)，如果您要得到一份整合的代碼文檔，您可以只在編譯順序中最后的那個(gè)項(xiàng)目配置中，填寫(xiě)這個(gè)生成后事件命令。如果您想為每個(gè)項(xiàng)目單獨(dú)生成一份文檔，則需要分別去配置。您可以根據(jù)您的實(shí)際情況決定。

關(guān)于 NDoc.bat 中的寫(xiě)法，您可以參考下面的命名行（它對(duì)應(yīng)于上面圖中的生成后事件命令）：

IF NOT %1 == Release GOTO end

"%ProgramFiles%\NDoc 1.3\bin\net\1.1\NDocConsole.exe" -recurse="%2bin\%1"

:end
　復(fù)雜的解決方案中，可能需要更加復(fù)雜的配置，比如有時(shí)配置第三方 dll 的搜索路徑等，仔細(xì)研究一下 NDocConsole.exe -help 的幫助信息吧！

其他開(kāi)發(fā)工具的配置
　大多數(shù)開(kāi)發(fā)工具都有運(yùn)行命令行程序的選項(xiàng)，這些開(kāi)發(fā)工具都可以使用 NDoc 命令行來(lái)實(shí)現(xiàn)代碼文檔的自動(dòng)生成。每種開(kāi)發(fā)工具的配置方法可能不同，但思路都很類(lèi)似上面關(guān)于 VS.NET 中的想法。

概述
　文檔引擎是生成各種格式代碼文檔的組件。NDoc 1.3 內(nèi)建了以下文檔引擎:

• VS.NET
• MSDN
• MSDN 2003
• XML
• JavaDoc
• LinearHtml
• LaTeX
  NDoc 的設(shè)計(jì)具有很強(qiáng)的可擴(kuò)展性，您可以自己創(chuàng)作輸出特定格式文檔的、新的文檔引擎。

代碼文檔的制作一般分作兩大環(huán)節(jié):

下面配置項(xiàng)，是 NDoc 所有文檔引擎中通用的配置項(xiàng)，各文檔引擎還可以有自己的一些特殊配置，詳見(jiàn)文檔引擎的文檔。

通用的配置

XLinks
　HTML Help 1 直接使用 HTML <A> 標(biāo)記表示超鏈接。Microsoft Help 2 引入了新的 XLinks 機(jī)制 (是微軟對(duì) W3C XLinks 的一個(gè)實(shí)現(xiàn))，來(lái)表示指向其他文檔集合的超鏈接。一個(gè) XLink 很像 HTML <A> 鏈接，但包含額外的元數(shù)據(jù)用于表示復(fù)雜的鏈接。Microsoft Help 2 使用 XLinks 不直接使用路徑/文件名，而根據(jù)在“索引”表中檢索特定的關(guān)鍵字查找。

NDoc 為指向 .NET Framework 類(lèi)型/成員的鏈接（包括成員列表中指向基類(lèi)型的鏈接、以及使用 <see> 標(biāo)記加入的指向 .NET Framework 或第三方類(lèi)庫(kù)中的類(lèi)型/成員的顯式鏈接），制作 XLinks 鏈接。下面是一個(gè)指向 System.Void 的示例 XLink:

<MSHelp:link

keywords="frlrfSystemVoidClassTopic"

indexMoniker="!DefaultAssociativeIndex"

namespace="ms-help://MS.NETFrameworkSDKv1.1.CHS">void</MSHelp:link>

上面 XLink 的三個(gè)屬性指示了查找這個(gè)幫助主題的方法。屬性 namespace 指示在哪個(gè)文檔命名空間中查找(每個(gè)幫助文檔集合都需要在機(jī)器中注冊(cè)一個(gè)唯一的命名空間，如上面的 ms-help://MS.NETFrameworkSDKv1.1.CHS 表示 .NET Framework SDK 類(lèi)庫(kù)文檔的幫助文檔集合)。屬性 indexMoniker 指示使用哪種類(lèi)型的“索引”(Microsoft Help 2 索引可以有很多類(lèi)型，其中，DefaultAssociativeIndex 常用于創(chuàng)建幫助主題之間的關(guān)聯(lián))。最后，keyword 指示要指向哪個(gè)幫助主題頁(yè)面。

每個(gè)頁(yè)面頭部的嵌入 XML 數(shù)據(jù)島中都包含若干 Keywords，您可以在 .NET Framework SDK 類(lèi)庫(kù)文檔中查看 System.Void 頁(yè)面中，包含如下的一行:

<MSHelp:Keyword Index="A" Term="frlrfSystemVoidMembersTopic"/>

這個(gè) frlrfSystemVoidMembersTopic 就是在 .NET Framework SDK 類(lèi)庫(kù)文檔中，用 DefaultAssociativeIndex 類(lèi)型的“索引”中的 keyword。

鏈接到 .NET Framework SDK 類(lèi)庫(kù)文檔
　指向到 .NET Framework SDK 類(lèi)庫(kù)文檔的超鏈接，不需要您費(fèi)心，NDoc 已經(jīng)可以做的很好。您盡管從 .NET Framework 的基類(lèi)型繼承、創(chuàng)作您的子類(lèi)型，或者使用 <see> 等標(biāo)記加入這些鏈接，NDoc 自動(dòng)處理這些關(guān)于 XLinks 的事情。

鏈接到第三方類(lèi)庫(kù)文檔
　NDoc 允許您創(chuàng)建指向到第三方類(lèi)庫(kù)文檔的超鏈接，不過(guò)也需要嚴(yán)格按照上面介紹的 XLinks 體制來(lái)做。首先找到該文檔集合的命名空間，和要指向的幫助主題 HTML 頁(yè)頭部中的 keyword，做好準(zhǔn)備。(如果那個(gè)文檔集合也是用 NDoc 1.3 生成的，則頁(yè)面頭部的 XML 數(shù)據(jù)島已經(jīng)按要求寫(xiě)好了 keyword。)

因?yàn)?NDoc 只能找到子類(lèi)型的父類(lèi)型的名稱(chēng)，<see> 標(biāo)記中最終 NDoc 看到的也只是要指向的類(lèi)型/成員的完全名稱(chēng)；NDoc 不知道這些類(lèi)型/成員的文檔存在哪個(gè)文檔集合中。您需要告訴 NDoc：哪些類(lèi)型/成員的幫助文檔在哪個(gè)文檔命名空間，而另一些類(lèi)型/成員在另一個(gè)文檔命名空間，也就是各 .NET 類(lèi)型/成員和 Microsoft Help 2 幫助文檔命名空間之間的映射關(guān)系。這就需要您指定 NamespaceMappingFile 了（請(qǐng)參見(jiàn) VS.NET 2003 文檔引擎的 UseHelpNamespaceMappingFile 配置項(xiàng)）。NamespaceMappingFile 是一個(gè) XML 文件，它必須符合 NamespaceMapping XSD 架構(gòu)(請(qǐng)右擊“另存為...”)。

<namespaceMap xmlns="urn:ndoc-sourceforge-net:documenters.NativeHtmlHelp2.schemas.namespaceMap">

<helpNamespace ns="ms-help://companyX.sharedhelpcollection">

<managedNamespace ns="CompanyX"/>

</helpNamespace>

<helpNamespace ns="ms-help://companyX.producthelpcollection">

<managedNamespace ns="CompanyX.Product1"/>

<managedNamespace ns="CompanyX.Product2"/>

</helpNamespace>

</namespaceMap>

NamespaceMappingFile 的 一個(gè)實(shí)例:

<?xml version="1.0" encoding="utf-8"?>
<namespaceMap xmlns="urn:ndoc-sourceforge-net:documenters.NativeHtmlHelp2.schemas.namespaceMap">
<helpNamespace ns="ms-help://MS.NETFrameworkSDKv1.1.CHS">
<managedNamespace ns="System" />
<managedNamespace ns="Microsoft" />
</helpNamespace>
</namespaceMap>

　上面的例子表示指向 System 和 Microsoft 命名空間的類(lèi)型/成員的鏈接，將被指向 ms-help://MS.NETFrameworkSDKv1.1.CHS 幫助文檔命名空間。

指定了 NamespaceMappingFile 之后，其他的工作都可以交給 NDoc 來(lái)做了。

與 Visual Studio .NET IDE 的集成

　.NET Framework SDK 類(lèi)庫(kù)文檔的每一個(gè)頁(yè)面的頭部都有一個(gè)嵌入的 XML 數(shù)據(jù)島。在 Microsoft 文檔資源管理器中，這些 XML 數(shù)據(jù)島用于創(chuàng)建索引，鏈接幫助主題，查找關(guān)鍵字，篩選幫助主題，以及很多其他功能。Visual Studio .NET IDE 中的“動(dòng)態(tài)幫助”功能也依賴(lài)于這些嵌入的 XML 數(shù)據(jù)。以下是一個(gè) XML 數(shù)據(jù)島示例：

<xml>

<MSHelp:TOCTitle Title="Object Class"/>

<MSHelp:RLTitle Title="Object Class"/>

<MSHelp:Keyword Index="K" Term="Object class, about Object class"/>

<MSHelp:Keyword Index="A" Term="frlrfSystemObjectClassTopic"/>

<MSHelp:Keyword Index="F" Term="System.Object"/>

<MSHelp:Attr Name="DocSet" Value="NETFramework"/>

<MSHelp:Attr Name="TopicType" Value="kbSyntax"/>

<MSHelp:Attr Name="DevLang" Value="CSharp"/>

<MSHelp:Attr Name="DevLang" Value="VB"/>

<MSHelp:Attr Name="DevLang" Value="C++"/>

<MSHelp:Attr Name="DevLang" Value="JScript"/>

<MSHelp:Attr Name="DevLang" Value="VJ#"/>

<MSHelp:Attr Name="Technology" Value="WFC"/>

<MSHelp:Attr Name="Technology" Value="ManagedC"/>

<MSHelp:Attr Name="TechnologyVers" Value="kbWFC"/>

<MSHelp:Attr Name="TechnologyVers" Value="kbManagedC"/>

<MSHelp:Attr Name="Locale" Value="kbEnglish"/>

<MSHelp:Attr Name="DocSet" Value="NETCompactFramework"/>

<MSHelp:Attr Name="TechnologyVers" Value="kbProfile2NETCF"/>

<MSHelp:Attr Name="HelpPriority" Value="2"/>

</xml>

NDoc VS.NET 文檔引擎同樣創(chuàng)建這樣的 XML 數(shù)據(jù)島，以提高和 Microsoft 文檔資源管理器以及 VS.NET IDE 的集成性。

要求

　盡管 NDoc 為每一幫助主題生成必要的 XML 數(shù)據(jù)島，但要更好的利用 Microsoft Help 2 的功能（如篩選器等），還需要了解更多的背景知識(shí)。

Help Title 必須存在于一個(gè)幫助集合中。

Microsoft Help 2 定義了兩個(gè)級(jí)別的幫助文檔容器：Help Title 和幫助集合。Help Title 是一組相關(guān)的幫助主題，編譯為一個(gè) .HxS 文件。幫助集合是一個(gè)或多個(gè) Help Title 的集合。(您可以這樣理解：一個(gè) Help Title 可以被當(dāng)作一個(gè)幫助集合，但反過(guò)來(lái)不成立。) 每個(gè)幫助集合必須分配有一個(gè)唯一的命名空間。

只有幫助集合才能被集成到 VS.NET 的幫助系統(tǒng)中。

幫助集合必須在每臺(tái)機(jī)器上注冊(cè)后才能被訪(fǎng)問(wèn)。

Microsoft Help 2 幫助系統(tǒng)維護(hù)一個(gè)注冊(cè)表(不要和 Windows 注冊(cè)表混淆)，保存當(dāng)前機(jī)器中所有已安裝的幫助集合。此注冊(cè)表用于定位超鏈接的目的地，執(zhí)行檢索，顯示索引等。這是 Microsoft Help 2 中一個(gè)核心的部分。

因?yàn)檫@個(gè)原因，幫助集合必須在安裝時(shí)注冊(cè)到每臺(tái)客戶(hù)端機(jī)器中，否則將無(wú)法訪(fǎng)問(wèn)得到。

已注冊(cè)的幫助集合可以被“plugged-in”進(jìn) VS.NET 合并文檔集合。

Microsoft Help 2 允許幫助集合的插接。可以將您的幫助集合插接到其他已有的幫助集合中，比如 VS.NET 合并文檔集合，它的命名空間是 MS.VSCC.2003。

還很糊涂？

　Microsoft Help 2 確實(shí)是一套復(fù)雜的技術(shù)。更深入的信息請(qǐng)查閱 VSHIK 文檔。網(wǎng)站 helpware.net 提供了很多有關(guān) Microsoft Help 2 的有用資料和教程。HelpWare 還提供了一個(gè)名為 FAR 的共享軟件，它更證明了 Microsoft Help 2 幫助系統(tǒng)的潛力。

VS.NET 文檔引擎使用了幾個(gè)配置項(xiàng)，意在簡(jiǎn)化整個(gè)過(guò)程。

首先，您應(yīng)該設(shè)置 GenerateCollectionFiles 為 true。這將指示 NDoc 將生成的文檔合并到 VS.NET 合并文檔集合中去。

然后，您需要指定 CollectionNamespace，幫助集合的命名空間名稱(chēng)。不要使用空格、漢字等 URI 中不允許的字符。建議您設(shè)法讓這個(gè)命名空間名稱(chēng)不容易重復(fù)，比如以您的公司名開(kāi)始，等等。

第三步，指定 PlugInNamespace。它表示要“plugged-in”到哪個(gè)文檔集合中去。當(dāng)使用 h2reg.exe 部署您的幫助文檔時(shí)，它們被插接到 VS.NET 的合并文檔集合中去。默認(rèn)值 ms.vscc 指示 h2reg.exe 自動(dòng)判斷 VS.NET 是 2002 或 2003 版本。

篩選器

　每個(gè)幫助主題的 XML 數(shù)據(jù)島中可以包含一個(gè)或多個(gè) DocSet 值。在文檔資源管理器及 VS.NET IDE 中，這些 DocSet 值常常被各個(gè)篩選器用于篩選幫助索引及搜索范圍。

默認(rèn)的一些篩選器定義如下:

將您的幫助集合加入上面這些篩選器的搜索范圍，可以很簡(jiǎn)單的指定文檔引擎的 DocSetList 配置項(xiàng)。它是一個(gè)逗號(hào)分隔的字符串，每一項(xiàng)最終都被寫(xiě)成 XML 數(shù)據(jù)島中的一行 DocSet 值。當(dāng)用戶(hù)使用這些篩選器時(shí)，如果您的幫助頁(yè)面 XML 數(shù)據(jù)島中具有特定的 DocSet 值，您的幫助文檔就會(huì)被包括在搜索范圍中。

NDoc 默認(rèn)將 HtmlHelpName 作為一行 DocSet 值寫(xiě)入每頁(yè)的 XML 數(shù)據(jù)島。您不需要通過(guò) DocSetList 重復(fù)定義它。

NDoc 默認(rèn)會(huì)注冊(cè)一個(gè)新的篩選器，這個(gè)篩選器的查詢(xún)條件是 "DocSet" = "HtmlHelpName"，即這個(gè)篩選器將只搜索這個(gè)幫助集合的內(nèi)容。Microsoft Help 2 允許您定義其他自定義的篩選器，但已經(jīng)超出 NDoc 的工作范圍，您需要自行查閱 VSHIK 文檔，修改 Microsoft Help 2 項(xiàng)目文件重新編譯。

部署 Microsoft Help 2

　Microsoft Help 2 幫助系統(tǒng)維護(hù)一個(gè)注冊(cè)表(不要和 Windows 注冊(cè)表混淆)，保存當(dāng)前機(jī)器中所有已安裝的幫助集合。注冊(cè)表保存了所有的幫助集合，每個(gè)幫助集合中包含的 Help Titles，幫助集合間的嵌套關(guān)系等。

查看 Microsoft Help 2 Title 或集合之前，必須首先注冊(cè)。因此 Microsoft Help 2 文檔的部署，要比 HTML Help 1 的簡(jiǎn)單文件拷貝復(fù)雜的多。

Windows Installer
　可以通過(guò)創(chuàng)建一個(gè) Windows Installer 安裝包程序，用于部署并注冊(cè)幫助集合和 Help Titles。VSHIK 文檔中有具體的制作步驟。不幸的是，這個(gè)過(guò)程中有很多手工的步驟，我們還沒(méi)有能夠找到自動(dòng)制作 Windows Installer 安裝包的方法。

H2Reg
　另一格選擇是使用 helpware.net 提供的 共享軟件 H2Reg.exe。H2Reg.exe 是一個(gè)命名行工具，可以在安裝過(guò)程中使用它，完成幫助集合/Help Title 的注冊(cè)。它可以被用于任何支持命令行的安裝程序，比如對(duì)于 Windows Installer 安裝包，H2Reg 可以作為一個(gè)自定義動(dòng)作。

如果設(shè)置 GenerateCollectionFiles 為 true，NDoc 會(huì)為 H2Reg 創(chuàng)建特定的 INI 配置文件，H2Reg 可以根據(jù)這個(gè) INI 配置文件完成 Help Title 的注冊(cè)、并合并到 VS.NET 的合并文檔集合等動(dòng)作。(記得將這個(gè) INI 配置文件包含進(jìn)您的安裝包。)

下面是完整的步驟:

注意: 先執(zhí)行 H2Reg，再刪除相應(yīng)的幫助文件和 INI 文件。

概述
　MSDN 文檔引擎用于生成如 .NET Framework SDK 類(lèi)庫(kù)文檔樣式的代碼文檔，并編譯為 HTML Help 1 格式的單一文件(*.CHM)。

MSDN 2003 文檔引擎是 NDoc 1.3 對(duì) MSDN 文檔引擎的改進(jìn)，加入了語(yǔ)言選擇器等功能，更加接近 .NET Framework SDK 文檔的樣式。

配置
　所有文檔引擎都具有一些 通用的配置項(xiàng)。

將附加的文件加入要編譯的 CHM 文件中

　MSDN 文檔引擎提供了 FilesToInclude 和 AdditionalContentResourceDirectory 兩種途徑，允許您附加額外的文件。

前者允許您使用 * 或 ? 通配符的形式指定要包含的文件路徑，可以指定多個(gè)路徑，用“|”隔開(kāi)。如果使用相對(duì)路徑，應(yīng)相對(duì)于 NDoc 項(xiàng)目文件所在的目錄。注意：在最終編譯的 CHM 中，這些被附加的文件，和其他由 NDoc 生成的 HTML 文件，處在同一級(jí)目錄中。

后者將一個(gè)文件夾中的內(nèi)容(包括子文件夾中的全部?jī)?nèi)容)全部讀入。注意：在最終編譯的 CHM 中，AdditionalContentResourceDirectory 文件夾第一級(jí)的文件和文件夾，和其他由 NDoc 生成的 HTML 文件，處在同一級(jí)目錄中；該目錄的子目錄及其中內(nèi)容，將保持原有父子關(guān)系。例如 AdditionalContentResourceDirectory 是 D:\temp ，這個(gè)目錄中有 my.css 文件和 images 子目錄，images 目錄中有 logo.gif 文件，則 my.css 和其他 NDoc 生成的文件同級(jí)，使用相對(duì)路徑引用 my.css 時(shí)為“my.css”；而引用 logo.gif 應(yīng)為“images/logo.gif”。

請(qǐng)根據(jù)您的具體情況進(jìn)行選擇具體采用哪種方式。

另外，RootPageFileName 指定 CHM 打開(kāi)時(shí)的第一個(gè)頁(yè)面文件，這個(gè)頁(yè)面可以是 NDoc 生成的文件，也可以是通過(guò)上述兩種方式附加進(jìn)去的某 HTML 文件。

概述
　MSDN 2003 文檔引擎是 NDoc 1.3 對(duì) MSDN 文檔引擎的改進(jìn)，加入了語(yǔ)言選擇器等功能，更加接近 .NET Framework SDK 文檔的樣式。它用于生成如 .NET Framework SDK 類(lèi)庫(kù)文檔樣式的代碼文檔，并編譯為 HTML Help 1 格式的單一文件(*.CHM)。

配置
　所有文檔引擎都具有一些 通用的配置項(xiàng)。

將附加的文件加入要編譯的 CHM 文件中
　MSDN 文檔引擎提供了 FilesToInclude 和 AdditionalContentResourceDirectory 兩種途徑，允許您附加額外的文件。

前者允許您使用 * 或 ? 通配符的形式指定要包含的文件路徑，可以指定多個(gè)路徑，用“|”隔開(kāi)。如果使用相對(duì)路徑，應(yīng)相對(duì)于 NDoc 項(xiàng)目文件所在的目錄。注意：在最終編譯的 CHM 中，這些被附加的文件，和其他由 NDoc 生成的 HTML 文件，處在同一級(jí)目錄中。

后者將一個(gè)文件夾中的內(nèi)容(包括子文件夾中的全部?jī)?nèi)容)全部讀入。注意：在最終編譯的 CHM 中，AdditionalContentResourceDirectory 文件夾第一級(jí)的文件和文件夾，和其他由 NDoc 生成的 HTML 文件，處在同一級(jí)目錄中；該目錄的子目錄及其中內(nèi)容，將保持原有父子關(guān)系。例如 AdditionalContentResourceDirectory 是 D:\temp ，這個(gè)目錄中有 my.css 文件和 images 子目錄，images 目錄中有 logo.gif 文件，則 my.css 和其他 NDoc 生成的文件同級(jí)，使用相對(duì)路徑引用 my.css 時(shí)為“my.css”；而引用 logo.gif 應(yīng)為“images/logo.gif”。

請(qǐng)根據(jù)您的具體情況進(jìn)行選擇具體采用哪種方式。

另外，RootPageFileName 指定 CHM 打開(kāi)時(shí)的第一個(gè)頁(yè)面文件，這個(gè)頁(yè)面可以是 NDoc 生成的文件，也可以是通過(guò)上述兩種方式附加進(jìn)去的某 HTML 文件。
　
　 概述
　XML 文檔引擎是 NDoc 中最簡(jiǎn)單的文檔引擎，它直接輸出 NDoc 生成的中間 XML 文件。主要幫助開(kāi)發(fā)人員調(diào)試 NDoc 擴(kuò)展 XSLT 轉(zhuǎn)換，以及制作新的自定義文檔引擎。

請(qǐng)參見(jiàn) NDoc 可擴(kuò)展性 和 實(shí)現(xiàn)一個(gè)新的文檔引擎。

配置
　所有文檔引擎都具有一些 通用的配置項(xiàng)。

概述
　JavaDoc 文檔引擎用于創(chuàng)建類(lèi)似 JavaDoc (Java 社區(qū)中，自動(dòng)創(chuàng)建代碼文檔的工具) 布局和格式的 HTML 代碼文檔。

因?yàn)槿鄙僮銐虻年P(guān)注度，此文檔引擎的開(kāi)發(fā)并不活躍。 如果您有興趣進(jìn)一步完善此文檔引擎，請(qǐng)聯(lián)絡(luò) NDoc 項(xiàng)目管理員。

配置
　所有文檔引擎都具有一些 通用的配置項(xiàng)。

概述
　Linear HTML 文檔引擎用于生成單一 HTML 文件的代碼文檔。

配置
　所有文檔引擎都具有一些 通用的配置項(xiàng)。

概述
　LaTeX 文檔引擎用于創(chuàng)建 dvi、pdf、postscript 等 LaTeX 格式的代碼文檔。

您需要安裝一個(gè) LaTeX 編譯器，比如免費(fèi)的 MiKTeX。關(guān)于 LaTeX 的中文支持問(wèn)題，請(qǐng)參見(jiàn) CTeX: 中文 TeX 網(wǎng)站 中的相關(guān)內(nèi)容。

配置
　所有文檔引擎都具有一些 通用的配置項(xiàng)。

NDoc 內(nèi)置的 MSDN, MSDN 2003, VS.NET 文檔引擎，支持 C# 程序員參考中的所有 XML 文檔注釋標(biāo)記。

NDoc 支持?jǐn)U充的標(biāo)記和語(yǔ)法。某些標(biāo)記只能用于特定的類(lèi)型（類(lèi)，結(jié)構(gòu)，委托，接口，枚舉）或成員（字段，屬性，方法，事件等），請(qǐng)參見(jiàn)標(biāo)記用法。

NDoc 將標(biāo)記區(qū)分為三類(lèi): Section 標(biāo)記，Block 標(biāo)記，Inline 標(biāo)記。

Section 標(biāo)記
　Section 標(biāo)記用于定義不同的代碼文檔的區(qū)域。它們都是頂級(jí)標(biāo)記，Block 標(biāo)記、Inline 標(biāo)記都應(yīng)包含在某個(gè) Section 標(biāo)記的內(nèi)部。（除非自定義了擴(kuò)展 XSLT 轉(zhuǎn)換，否則，在 Section 標(biāo)記外部的 Block 標(biāo)記或 Inline 標(biāo)記都被忽略。）

Block 標(biāo)記
　Block 標(biāo)記用于 Section 標(biāo)記的內(nèi)部，它們將顯示在單獨(dú)的行中。

Inline 標(biāo)記
　Inline 標(biāo)記可以用于其他 Section 標(biāo)記或 Block 標(biāo)記內(nèi)部，它們將和前后的文本顯示在同一行中。

下面的表格顯示了各 block 標(biāo)記的有效性。

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

<c>text</c>
　其中:

text
　要標(biāo)記為代碼樣式的文本。
　應(yīng)用于
　可用于其他標(biāo)記內(nèi)部。

備注
　如果需要標(biāo)記多行的代碼塊，請(qǐng)使用 <code> 標(biāo)記。

示例
　[C#]
　public class MyClass
　{
　/// <summary>
　/// <c>MyMethod</c> is a method in the <c>MyClass</c> class.
　/// </summary>
　public static void MyMethod(int Int1)
　{
　}
　}

　 <code> 標(biāo)記指示將其內(nèi)部的文本表示為代碼樣式，Block 標(biāo)記，用于表示多行的代碼塊。

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

lang="language" [NDoc 擴(kuò)充]
　語(yǔ)言選擇器，表示此代碼塊僅適用于某種編程語(yǔ)言。(可選)
　escaped="true" [NDoc 擴(kuò)充]
　若 content 中含有 XML 子級(jí)，將它們視為代碼的一部分。注意：content 仍然需要是格式完好的 XML。(可選)
　content
　將被表示為代碼塊的文本。
　應(yīng)用于
　可用于其他 Section 標(biāo)記或 Block 標(biāo)記內(nèi)部。

備注
　使用 lang 屬性表示語(yǔ)言選擇器，標(biāo)準(zhǔn)的語(yǔ)言有: Visual Basic, C#, C++ 及 JScript。若代碼塊適用于多種語(yǔ)言，則用逗號(hào)隔開(kāi)，比如“Visual Basic, C#, C++”。

escaped 為 true 時(shí)，其內(nèi)部所有其他標(biāo)記都被轉(zhuǎn)義為代碼塊的一部分。

注意 content 內(nèi)容必須是格式完好的 XML 注釋。否則整個(gè)注釋塊可能被忽略或出錯(cuò)!!!

示例
　下面示例中，因?yàn)?escaped="true"，因此直接寫(xiě)入了要作為代碼塊的 XML 內(nèi)容。 Note how, in the following comments, the xml text can entered verbatim because the escaped="true" attribute has been applied.

[C#]
　/// <summary>
　/// Loads the XML.
　/// </summary>
　/// <example> The XML should have the following format.
　/// <code escaped="true">
　/// <root>
　/// <member name="name"/>
　/// </root>
　/// </code>
　/// </example>
　public void LoadXml(string xml)
　{
　//do something here...
　}

<event> 標(biāo)記用于說(shuō)明被標(biāo)記的方法可能引發(fā)的事件。Section 標(biāo)記。

<event cref="member">description</event>
　其中:

cref = "member"
　表示可能引發(fā)的事件。書(shū)寫(xiě)時(shí)，如果可能引發(fā)的事件是同一類(lèi)型的事件，member 可以直接寫(xiě)事件名稱(chēng)（注意大小寫(xiě)）；如果是其他類(lèi)型的，建議您寫(xiě)該事件的完全限定名稱(chēng)。C# 編譯器將檢查該事件是否存在。在輸出的 XML 文檔文件中，C# 編譯器會(huì)自動(dòng)轉(zhuǎn)換簡(jiǎn)寫(xiě)的 member 為完全限定名稱(chēng)。
　description
　附加的說(shuō)明，比如在什么情況下引發(fā)該事件。
　應(yīng)用于
　方法成員。

備注

示例

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

<example>description</example>
其中:

description
示例及其說(shuō)明。
應(yīng)用于
所有的類(lèi)型及成員。

備注
此標(biāo)記經(jīng)常和 <code> 標(biāo)記聯(lián)用。

示例
[C#]
public class MyClass
{
/// <summary>
/// The GetZero method.
/// </summary>
/// <example> This sample shows how to call the GetZero method.
/// <code>
/// class MyClass
/// {
/// public static int Main()
/// {
/// return GetZero();
/// }
/// }
/// </code>
/// </example>
public static int GetZero()
{
return 0;
}
}

<exception> 標(biāo)記用于說(shuō)明一個(gè)成員可能拋出的異常。

<exception cref="member">description</exception>
其中:

cref = "member"
表示可能拋出的異常類(lèi)型。書(shū)寫(xiě)時(shí)，如果可能拋出的異常是同一命名空間下的異常類(lèi)型，member 可以直接寫(xiě)異常名稱(chēng)（注意大小寫(xiě)）；如果是其他命名空間的，建議您寫(xiě)該異常類(lèi)型的完全限定名稱(chēng)。C# 編譯器將檢查該異常是否存在。在輸出的 XML 文檔文件中，C# 編譯器會(huì)自動(dòng)轉(zhuǎn)換簡(jiǎn)寫(xiě)的 member 為完全限定名稱(chēng)。
description
說(shuō)明信息，比如在什么情況下拋出該異常。
應(yīng)用于
屬性, 方法, 事件, 運(yùn)算符, 類(lèi)型轉(zhuǎn)換

備注

示例
[C#]
using System;

/// comment for class
public class EClass : Exception
{
// class definition ...
}

class TestClass
{
/// <exception cref="EClass">Thrown when... .</exception>
public static void Main()
{
...
throw new EClass();
...
}
}

<exclude/> 標(biāo)記指示 NDoc 文檔引擎將被標(biāo)記的類(lèi)型/成員排除在代碼文檔之外。

<exclude/>
應(yīng)用于
所有的類(lèi)型及成員。

備注
與文檔引擎的“可見(jiàn)性”配置不符的，以 exclude 優(yōu)先。

示例
請(qǐng)參見(jiàn)

<include> 標(biāo)記指示將代碼文件(*.cs)外部的某 XML 文件中的一部分、作為 XML 文檔注釋、包含進(jìn)代碼文件來(lái)。

<include file='filename' path='tagpath[@name="id"]' />
其中:

filename
包含 XML 文檔注釋的文件名。該文件名可包含路徑。將 filename 括在單引號(hào)中 (' ')。
tagpath
filename 中指向標(biāo)記名的標(biāo)記路徑（使用 XPath 語(yǔ)法）。將此路徑括在單引號(hào)中 (' ')。
name
注釋前邊的標(biāo)記中的名稱(chēng)說(shuō)明符；名稱(chēng)具有一個(gè) id。
id
位于注釋之前的標(biāo)記的 ID。將此 ID 括在雙引號(hào)中 (" ")。
應(yīng)用于
所有的類(lèi)型及成員。

備注
這是除了將文檔注釋直接置于源代碼文件中之外的另一種可選方法。

<include> 標(biāo)記使用 XML XPath 語(yǔ)法。有關(guān)自定義 <include> 使用的方法，請(qǐng)參見(jiàn) XPath 文檔。

示例
以下是一個(gè)多文件示例。第一個(gè)文件使用 <include>，如下所列：

[C#]
/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' />
class Test
{
public static void Main()
{
}
}

/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test2"]/*' />
class Test2
{
public void Test()
{
}
}
第二個(gè)文件 xml_include_tag.doc 包含下列文檔注釋：

<MyDocs>

<MyMembers name="test">
<summary>
The summary for this type.
</summary>
</MyMembers>

<MyMembers name="test2">
<summary>
The summary for this other type.
</summary>
</MyMembers>

</MyDocs>
編譯器輸出的 XML 文檔
<?xml version="1.0"?>
<doc>
<assembly>
<name>t2</name>
</assembly>
<members>
<member name="T:Test">
<summary>
The summary for this type.
</summary>
</member>
<member name="T:Test2">
<summary>
The summary for this other type.
</summary>
</member>
</members>
</doc>

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

<list type="bullet" | "number" | "table" | "definition">
<listheader>
<term>term</term>
<description>description</description>
</listheader>
<item>
<term>term</term>
<description>description</description>
</item>
</list>
其中:

term
要定義的項(xiàng)，該項(xiàng)將在 description 中說(shuō)明/定義。
description
對(duì) term 的說(shuō)明/定義。
備注
<list> 可以表示為四種樣式：bullet 為符號(hào)列表，即對(duì)應(yīng)于 HTML 中的 UL 列表；number 為數(shù)字列表，即對(duì)應(yīng)于 HTML 中的 OL 列表；table 為表格，將以表格形式表示；definition 為定義列表，顯示效果就像本頁(yè)上方“其中”二字下面對(duì) term 和 description 的定義那樣。

<listheader> 對(duì) table 和 definition 有效。對(duì) table，需要為 term 和 description 兩列分別指定列標(biāo)題。對(duì) definition，需要指定標(biāo)題文本，如本頁(yè)上方的“其中:”那一行。

<item> 塊表示列表中的一項(xiàng)。item 包含子元素 term 和 description。對(duì) bullet 和 number 列表，term 無(wú)效也不需要寫(xiě)。對(duì) table 表，可以沒(méi)有 term，只寫(xiě) description。對(duì) definition 表，term 和 description 都應(yīng)該有。

列表可以根據(jù)需要包含多個(gè) <item> 塊。

示例

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

<note type="caution" | "inheritinfo" | "implementnotes">
description
</note>

其中:

description
注意事項(xiàng)。
應(yīng)用于
可用于其他標(biāo)記內(nèi)部。

備注
caution 將顯示為“警告”，inheritinfo 將顯示為“對(duì)繼承者的說(shuō)明”，implementnotes 將顯示為“對(duì)實(shí)施者的說(shuō)明”。

示例

　 <overloads> 標(biāo)記為“重載列表”頁(yè)面提供文檔。

簡(jiǎn)單語(yǔ)法
<overloads>
summary_description
</overloads>

復(fù)合語(yǔ)法
<overloads>
<summary>summary_description</summary>
[<remarks>remarks_description</remarks>]
[<example>examples_description</example>]
</overloads>

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

備注
只需在重載成員的第一個(gè)成員前面書(shū)寫(xiě)此區(qū)域即可。

此標(biāo)記有兩種形式:

簡(jiǎn)單的形式，直接在 overload 中寫(xiě)文本，這些文本被處理為“重載列表”頁(yè)面的摘要。沒(méi)有備注、示例等區(qū)域。
復(fù)雜的形式，在 overload 內(nèi)部，包含 summary, remarks, example 等標(biāo)記分別表示“重載列表”頁(yè)面的摘要、備注、示例等。
示例

<para> 標(biāo)記表示一個(gè)段落。

<para [lang="language"]>content</para>
where:

lang="language" [NDoc 擴(kuò)充]
表示語(yǔ)言選擇器，指示此段落僅對(duì)某種編程語(yǔ)言有效。(可選)
content
段落文本。
應(yīng)用于
可用于其他標(biāo)記內(nèi)部。

備注
此標(biāo)記經(jīng)常用于 <summary>, <remarks>, 及 <returns> 等標(biāo)記內(nèi)部。

使用 lang 屬性表示語(yǔ)言選擇器，標(biāo)準(zhǔn)的語(yǔ)言有: Visual Basic, C#, C++ 及 JScript。若代碼塊適用于多種語(yǔ)言，則用逗號(hào)隔開(kāi)，比如“Visual Basic, C#, C++”。

示例
請(qǐng)參見(jiàn) <summary> 的示例。

The <param> tag describes one of the parameters for the method.

<param name='name'>description</param>
where:

name
The name of a method parameter. Enclose the name in single quotation marks (' ').
description
A description for the parameter.
Applies To
Property, Method, Event, Operator.

Remarks
Example
[C#]
/// text for class MyClass
public class MyClass
{
/// <param name="Int1">Used to indicate status.</param>
public static void MyMethod(int Int1)
{
}
/// text for Main
public static void Main ()
{
}
}
See Also

　 <paramref> 標(biāo)記引用一個(gè)參數(shù)，將以代碼樣式表示該參數(shù)名稱(chēng)。

<paramref name="name"/>
其中:

name
參數(shù)的名稱(chēng)。
應(yīng)用于
可用于其他標(biāo)記內(nèi)部。

備注
示例
[C#]
/// text for class MyClass
public class MyClass
{
/// <remarks>MyMethod is a method in the MyClass class.
/// The <paramref name="Int1"/> parameter takes a number.
/// </remarks>
public static void MyMethod(int Int1)
{
}

/// text for Main
public static void Main ()
{
}
}

　 <permission> 標(biāo)記說(shuō)明訪(fǎng)問(wèn)某成員所必需的 .NET Framework 安全性 CodeAccessPermission。

<permission cref="member">description</permission>
其中:

cref = "member"
表示需要的 CodeAccessPermission 類(lèi)型。書(shū)寫(xiě)時(shí)，如果 CodeAccessPermission 是同一命名空間下的類(lèi)型，member 可以直接寫(xiě)其名稱(chēng)（注意大小寫(xiě)）；如果是其他命名空間的，建議您寫(xiě)該 CodeAccessPermission 的完全限定名稱(chēng)。C# 編譯器將檢查該 CodeAccessPermission 是否存在。在輸出的 XML 文檔文件中，C# 編譯器會(huì)自動(dòng)轉(zhuǎn)換簡(jiǎn)寫(xiě)的 member 為完全限定名稱(chēng)。
description
其他說(shuō)明。
應(yīng)用于
所有成員。

備注
System.Security.PermissionSet 使您得以指定對(duì)成員的訪(fǎng)問(wèn)。

示例
[C#]
using System;
class TestClass
{
/// <permission cref="System.Security.PermissionSet">Everyone can access this method.</permission>
public static void Test()
{
}
public static void Main()
{
}
}
　
　 <preliminary> 標(biāo)記將類(lèi)型/成員標(biāo)記為“預(yù)發(fā)布”。

<preliminary>[description]</preliminary>
其中:

description
對(duì)“預(yù)發(fā)布”的說(shuō)明文本。(可選)
應(yīng)用于
所有的類(lèi)型及成員。

備注
若沒(méi)有指定 description，則以紅色顯示默認(rèn)的文本: “[此文檔為預(yù)發(fā)布版本，在未來(lái)版本中有可能改變。]”

如果需要把全部類(lèi)型/成員都標(biāo)記為“預(yù)發(fā)布”，請(qǐng)使用文檔引擎的 Preliminary 配置項(xiàng)。

示例
[C#]
// The class summary will get the default message
/// <preliminary/>
public class MyClass
{
/// <preliminary>
/// <para>This method is just for testing right now. It might be removed in the near future</para>
/// </preliminary>
public void Dump ()
{
}
}

　 <remarks> 標(biāo)記表示對(duì)類(lèi)型或成員的“備注”。

<remarks>description</remarks>
其中:

description
對(duì)類(lèi)型/成員的“備注”。
應(yīng)用于
所有的類(lèi)型及成員。

備注
<remarks> 標(biāo)記用于對(duì) <summary> 摘要信息的補(bǔ)充。.

示例
[C#]
/// <summary>
/// You may have some primary information about this class.
/// </summary>
/// <remarks>
/// You may have some additional information about this class.
/// </remarks>
public class MyClass
{
/// text for Main
public static void Main ()
{
}
}

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

<returns>description</returns>
其中:

description
對(duì)方法的返回值的說(shuō)明。
應(yīng)用于
方法。

備注
示例
[C#]
/// text for class MyClass
public class MyClass
{
/// <returns>Returns zero.</returns>
public static int GetZero()
{
return 0;
}

/// text for Main
public static void Main ()
{
}
}

　 <see> 標(biāo)記用于在行文中添加一個(gè)超鏈接。

<see cref="member">[label]</see>
或
<see href="URL">[label]</see>
或
<see langword="null | sealed
| static | abstract | virtual | true | false"/>
其中:

label
超鏈接的顯示文本。
cref = "member"
表示要鏈接到的類(lèi)型(成員)。書(shū)寫(xiě)時(shí)，如果要鏈接到的類(lèi)型(成員)是同一命名空間(類(lèi)型)中的類(lèi)型(成員)，member 可以直接寫(xiě)它的名稱(chēng)（注意大小寫(xiě)）；如果是其他命名空間(類(lèi)型)的，建議您寫(xiě)該類(lèi)型(成員)的完全限定名稱(chēng)。C# 編譯器將檢查該類(lèi)型(成員)是否存在。在輸出的 XML 文檔文件中，C# 編譯器會(huì)自動(dòng)轉(zhuǎn)換簡(jiǎn)寫(xiě)的 member 為完全限定名稱(chēng)。
href = "URL" [NDoc 擴(kuò)充]
一個(gè)網(wǎng)絡(luò) URL 地址。
langword [NDoc 擴(kuò)充]
將會(huì)被當(dāng)作 .NET 關(guān)鍵字粗體顯示。如果 langword 是下面?zhèn)渥⒅械谋砀窭锏哪硞€(gè)關(guān)鍵字，還將會(huì)被替換為相應(yīng)的說(shuō)明文本。
應(yīng)用于
可用于其他標(biāo)記內(nèi)部。

備注
　使用 <seealso> 標(biāo)記將超鏈接加入到頁(yè)面的“請(qǐng)參見(jiàn)”區(qū)域。

注意: 在 NDoc 1.3 中，對(duì)于 MSDN 和 VS.NET 文檔引擎，如果一個(gè)區(qū)域出現(xiàn)了多個(gè)指向同一個(gè)類(lèi)型/成員的文檔的 <see>，則只轉(zhuǎn)換第一個(gè)為超鏈接，其余的不表示為超鏈接、只顯示為粗體。這將使頁(yè)面不至于太雜亂。

可識(shí)別的 langword
　如果 langword 為下表中的關(guān)鍵字之一，則會(huì)顯示右側(cè)相應(yīng)的說(shuō)明文本。

示例
　請(qǐng)參見(jiàn) <summary> 中的示例。

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

<seealso cref="member">[label]</seealso>
或
<seealso href="URL">[label]</seealso>
其中:

label
超鏈接的顯示文本。
cref = "member"
表示要鏈接到的類(lèi)型(成員)。書(shū)寫(xiě)時(shí)，如果要鏈接到的類(lèi)型(成員)是同一命名空間(類(lèi)型)中的類(lèi)型(成員)，member 可以直接寫(xiě)它的名稱(chēng)（注意大小寫(xiě)）；如果是其他命名空間(類(lèi)型)的，建議您寫(xiě)該類(lèi)型(成員)的完全限定名稱(chēng)。C# 編譯器將檢查該類(lèi)型(成員)是否存在。在輸出的 XML 文檔文件中，C# 編譯器會(huì)自動(dòng)轉(zhuǎn)換簡(jiǎn)寫(xiě)的 member 為完全限定名稱(chēng)。
href = "URL" [NDoc 擴(kuò)充]
一個(gè)網(wǎng)絡(luò) URL 地址。
應(yīng)用于
所有的類(lèi)型及成員。

備注
使用 <see> 標(biāo)記在行文中添加超鏈接。

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

示例
請(qǐng)參見(jiàn) <summary> 中的示例。

<summary> 標(biāo)記用于對(duì)類(lèi)型或成員的摘要說(shuō)明。

<summary>description</summary>
其中:

description
對(duì)類(lèi)型或成員的摘要說(shuō)明。
應(yīng)用于
所有的類(lèi)型及成員。

備注
此標(biāo)記是所有類(lèi)型及成員最基本的說(shuō)明，一般的，應(yīng)為每個(gè)公共的、可見(jiàn)的類(lèi)型/成員書(shū)寫(xiě) summary 文檔。在 Visual Studio .NET IDE 的智能感知功能及對(duì)象查看器，還有其他大多數(shù)開(kāi)發(fā)工具，都會(huì)顯示 summary 信息。

<remarks> 標(biāo)記用于更詳細(xì)的說(shuō)明。

示例
[C#]
/// text for class MyClass
public class MyClass
{
/// <summary>MyMethod is a method in the MyClass class.
/// <para>Here's how you could make a second paragraph in a description. <see cref="System.Console.WriteLine"/> for information about output statements.</para>
/// <seealso cref="MyClass.Main"/>
/// </summary>
public static void MyMethod(int Int1)
{
}

/// text for Main
public static void Main ()
{
}
}

　 <threadsafety> 標(biāo)記用于說(shuō)明類(lèi)型在多線(xiàn)程環(huán)境中是否安全。
<threadsafety static="true|false" instance="true|false"/>
其中:

static="true|false"
指示類(lèi)型的靜態(tài)成員在多線(xiàn)程環(huán)境中是否是安全的。
instance="true|false"
指示類(lèi)型的實(shí)例成員在多線(xiàn)程環(huán)境中是否是安全的。
應(yīng)用于
類(lèi), 結(jié)構(gòu)。

備注
示例
[C#]
/// <threadsafety static="true" instance="false"/>
public class MyClass
{
/// not safe across threads
public void InstanceMethod()
{
}

/// safe across threads
public static void StaticMethod()
{
}
}

<value> 標(biāo)記用于說(shuō)明屬性的值。

<value>property-description</value>
其中:

property-description
對(duì)屬性值的說(shuō)明。
應(yīng)用于
屬性。

備注
按照約定，總是應(yīng)該為屬性書(shū)寫(xiě) <value> 標(biāo)記。

示例
[C#]
/// text for class MyClass
public class MyClass
{
/// <summary>MyProperty is a property in the MyClass class.</summary>
/// <value>A string containing the text "MyProperty String".</value>
public string MyProperty()
{
get
{
return "MyProperty String";
}
}

}

NDoc 可擴(kuò)展性
MSDN, MSDN 2003 和 VS.NET 文檔引擎都支持一個(gè)可擴(kuò)展的模型，允許您定義自己專(zhuān)有的標(biāo)記，并指定它們?cè)诖a文檔中呈現(xiàn)的樣式。您或許已經(jīng)知道，這些文檔引擎都使用 XSLT 轉(zhuǎn)換，將 NDoc 中間 XML 數(shù)據(jù)文件轉(zhuǎn)換為目標(biāo) HTML 格式。NDoc 標(biāo)記的可擴(kuò)展性也依賴(lài)于此，您可以通過(guò)自定義的 XSLT 轉(zhuǎn)換文件加入您自定義的標(biāo)記。（建議，您需要事先了解一些 XSLT 轉(zhuǎn)換的知識(shí)，并分析 XML 文檔引擎生成的 NDoc 中間 XML 數(shù)據(jù)文件中的 XML 格式，經(jīng)過(guò)足夠的測(cè)試，以調(diào)試您自己的擴(kuò)展 XSLT 轉(zhuǎn)換。）

第一步，是在您的 C# 代碼中加入您的自定義標(biāo)記: (注意紅色的自定義標(biāo)記)

[C#]
/// <myTag>This is a custom tag</myTag>
/// <summary>
/// When processed by the VS.NET or MSDN documenters,
/// using the stylesheet "extend-ndoc.xslt" as the ExtensibilityStylesheet
/// property will result in end-user defined tags being displayed in the
/// final help output topics
/// </summary>
/// <remarks>This is a test of an inline <null/> tag</remarks>
public class ABunchOfCustomTags
{
}

在編譯后生成的 /doc 文檔中，您可以找到這些自定義的標(biāo)記。

接下來(lái)，創(chuàng)建您的 XSLT 轉(zhuǎn)換模板，控制那些自定義標(biāo)記的輸出位置和樣式:

<xsl:stylesheet version="1.0" xmlns:xsl=http://www.w3.org/1999/XSL/Transform xmlns:MSHelp="http://msdn.microsoft.com/mshelp">

<xsl:template match="node()" mode="xml-data-island" priority="1">

<MSHelp:Attr Name="TargetOS" Value="Windows"/>

</xsl:template>

<xsl:template match="ndoc" mode="header-section">

<style type="text/css">

.green

{

color:green;

}

</style>

</xsl:template>
<xsl:template match="myTag" mode="seealso-section">

<h1 class="green">

<xsl:value-of select="." mode="slashdoc"/>

</h1>

</xsl:template>

<xsl:template match="null" mode="slashdoc">

<xsl:text> null reference (Nothing in Visual Basic) </xsl:text>

</xsl:template>

</xsl:stylesheet>

您應(yīng)該確認(rèn) XSLT 標(biāo)記的完整和語(yǔ)法的正確，注意 XSLT namespace 是必須的。

如上面示例中看到的那樣，使用 stylesheet 中的 templates“匹配(match)”您的自定義標(biāo)記。match 是 XPath 查詢(xún)的一種，指示 template 將應(yīng)用于哪些標(biāo)記。簡(jiǎn)單的用法是直接匹配您的自定義標(biāo)記，當(dāng)然還可以有更高級(jí)的用法，對(duì) XSLT 高手們應(yīng)當(dāng)是小菜一碟。

注意: 如果您定義的自定義標(biāo)記中還包含其他標(biāo)記，您應(yīng)當(dāng)加入下面的命令，讓它轉(zhuǎn)換這些內(nèi)含的標(biāo)記(比如 <see> 等)：
<xsl:apply-templates select="." mode="slashdoc"/>
上例中還展示了向 HTML HEAD 頭部添加附加樣式定義的方法，即使用 mode 為 header-section 的 template。使用這種方法您可以覆蓋 NDoc 默認(rèn)的樣式或者添加附加的樣式表等。

什么是 mode 呢？mode 用于指定該內(nèi)容將顯示于文檔的哪些區(qū)域。NDoc 擴(kuò)展的自定義標(biāo)記可以是以下兩類(lèi):

Section 標(biāo)記 - 塊標(biāo)記，將顯示于文檔的某個(gè)區(qū)域。為 section 標(biāo)記編寫(xiě) template 時(shí)，mode 必須是預(yù)定義的可用 Section 的列表中的一個(gè)。
Inline 標(biāo)記 - 將和其他注釋文本夾雜在一起。為 inline 標(biāo)記編寫(xiě) template 時(shí)，mode 必須是 "slashdoc"。
如果您準(zhǔn)備編寫(xiě)匹配一些泛型 XPath 查詢(xún)，如 node(), text(), *, 或 @*，您應(yīng)當(dāng)給該 template 指定一個(gè)名為 priority、值大于 0.5 的屬性，用您編寫(xiě)的 template 替換 NDoc 默認(rèn)的轉(zhuǎn)換模板。

請(qǐng)注意: XSLT 是大小寫(xiě)敏感的，match 查詢(xún)模式，以及 mode 值都必須使用正確的大小寫(xiě)，否則將被忽略。

最后，為 MSDN 或 VS.NET 文檔引擎設(shè)置 ExtensibilityStylesheet 配置，指向您創(chuàng)作好的 XSLT 轉(zhuǎn)換文件。然后使用 NDoc 生成代碼文檔，您將看到已經(jīng)按照您編寫(xiě)的 template 規(guī)則執(zhí)行了相應(yīng)轉(zhuǎn)換。

一張屏幕截圖:

輸出示例

可用 Section 的列表
下面列出了所有可用 section 的清單，它們用于 NDoc 擴(kuò)展 XSLT 轉(zhuǎn)換模板中 mode 屬性的值，指示該標(biāo)記將顯示在代碼文檔中的區(qū)域。

實(shí)現(xiàn)一個(gè)新的文檔引擎
　實(shí)現(xiàn)一個(gè)新的文檔引擎至少需要編寫(xiě)兩個(gè)類(lèi):

一個(gè)從 NDoc.Core.DocumenterBase 繼承而來(lái)的類(lèi)

一個(gè)從 NDoc.Core.DocumenterConfigBase 繼承而來(lái)的類(lèi)

DocumenterConfigBase 是用于存儲(chǔ)文檔引擎配置信息的基類(lèi)。它已經(jīng)包含了一些通用的配置項(xiàng)，這些通用配置主要用于配置 NDoc 中間 XML 數(shù)據(jù)文件的生成動(dòng)作。您編寫(xiě)的子類(lèi)可以添加所需要的特定配置項(xiàng)(比如生成的文檔保存在什么路徑下等)。

DocumenterBase 是文檔引擎的基類(lèi)。文檔引擎的工作模式是，第一步生成 NDoc 中間 XML 數(shù)據(jù)文件，第二步由各文檔引擎將中間 XML 數(shù)據(jù)文件、分別轉(zhuǎn)換成所需的最終文檔格式。此基類(lèi)完成了第一步的工作，您編寫(xiě)的子類(lèi)只需完成第二個(gè)步驟。

必須實(shí)現(xiàn)的成員包括 Clear, Build 方法以及 MainOutputFile 屬性等抽象(abstract)成員。

實(shí)現(xiàn) Build 方法時(shí), 可以調(diào)用基類(lèi)的 MergeXML 方法，它完成第一步的 NDoc 中間 XML 數(shù)據(jù)文件的合并和制作。

使用 XML 文檔引擎 可以導(dǎo)出一個(gè) NDoc 中間 XML 數(shù)據(jù)文件的樣例。您可以通過(guò)分析它，調(diào)試您的自定義轉(zhuǎn)換代碼或 XSLT 轉(zhuǎn)換定義。使用 UseNDocXmlFile 配置項(xiàng)，可以節(jié)省您的調(diào)試時(shí)間。

文檔引擎是如何加載的
　NDoc 通過(guò)反射發(fā)出(Reflection)機(jī)制動(dòng)態(tài)分析和加載文檔引擎。NDoc 啟動(dòng)時(shí)，自動(dòng)檢查程序(NDocGui.exe 或 NDocConsole.exe)所在路徑中、所有以如下格式命名的程序集:

NDoc.Documenter.<NAME>.dll

其中 <NAME> 是文檔引擎的名稱(chēng)(注: 可能與界面中顯示的名稱(chēng)不同)。

NDoc 從這些程序集中分析、嘗試查找 DocumenterBase 的子類(lèi)，并加載找到的文檔引擎。

為 NDoc 貢獻(xiàn)代碼
您可以有很多種選擇，為 NDoc 的開(kāi)發(fā)做出有益的貢獻(xiàn)。

• 加入 ndoc-users 郵件列表 是最簡(jiǎn)單的方式、和其他用戶(hù)分享您的使用心得體會(huì)和經(jīng)驗(yàn)。
• 如果您發(fā)現(xiàn)了 bug，或者有一些不錯(cuò)的新功能建議，請(qǐng)使用 NDoc tracker database， 讓我們了解您的發(fā)現(xiàn)和想法。
• 如果您有更多空閑的時(shí)間，希望成為 NDoc 開(kāi)發(fā)組的成員、和我們一起實(shí)現(xiàn)那些 new features 或者修復(fù)那些已知的 bugs，請(qǐng)通過(guò)NDoc SourceForge 站點(diǎn)聯(lián)絡(luò)項(xiàng)目的負(fù)責(zé)人、管理員，我們會(huì)幫助您開(kāi)始工作。我們歡迎越來(lái)越多的人們加入 NDoc 隊(duì)伍！
• 感謝您使用 NDoc！

NDoc 用戶(hù)郵件列表
　您也可以搜索 ndoc-users 郵件列表的存檔郵件，或者發(fā)送問(wèn)題到這個(gè)郵件列表。

NDoc 跟蹤數(shù)據(jù)庫(kù)
　如果通過(guò)以上途徑還是沒(méi)有找到您要的答案，您可以嘗試 NDoc 在 SourceForge.net 維護(hù)的 Tracker database。

• 提交一個(gè)支持請(qǐng)求(support request)
• 提交 Bug 報(bào)告
• 提交新功能建議

介紹 NDoc 的文章
　網(wǎng)絡(luò)中還有很多不錯(cuò)的 NDoc 介紹文章，下面有些文章發(fā)布時(shí)間很早，有些鏈接已經(jīng)失效了。

• [Documenting C# with XML comments], 作者 Ollie Cornes
• [Using NDoc: Adding World-Class Documentation to Your .NET Components], 作者 Shawn Van Ness
• [Fixing NDoc to emit links for Everett's MSDN docs], 作者 Shawn Van Ness
• [Integrate NDoc HTML Help 2 in Visual Studio.NET], 作者 Fons Sonnemans
• [Creating class documentation with NDoc], 作者 Rick Harris
• [Integrating Help into Visual Studio.NET], 作者 Sune Trudslev?