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

關于 NDoc
　NDoc 可以將 C#.NET 編譯生成的程序集和對應的 /doc XML 文檔，自動轉換成如 .NET Framework SDK 類庫文檔或者 MSDN Library 在線 .NET 類庫文檔形式的代碼文檔，讓您快速擁有專業級的類庫API 文檔。(VB.NET 通過第三方插件如 VBCommenter 的支持，也可以生成 XML 文檔。)

　NDoc 代碼文檔的樣式包括 HTML Help 1 (即 *.CHM 格式)，Microsoft Help 2 (即以形如 ms-help://... 的 URI 地址訪問的文檔)，以及 MSDN 在線網頁樣式的 .NET Framework 類庫文檔。

NDoc 為開放源代碼項目，采用 GNU General Public Licence 授權協議（除非您的軟件/項目也采用 GPL 協議開放源代碼，否則您不能在您的軟件/項目中使用 NDoc 源代碼中的任何部分）。更多的授權問題，請參見 GNU FAQ。

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

使用 NDoc 之前
請閱讀 GNU General Public Licence 和 GNU FAQ。

請閱讀 已知問題。

請閱讀 必要的幫助文件編譯器。

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

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

NDoc 1.3 - What's new?
　NDoc 1.3 包含了大量更新和改進，也修復了許多 bug。

亮點
　NDoc 1.3 包含了許多新功能:

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

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

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

更多的細節請參看 VS.NET 2003 文檔引擎。

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

• NDoc 中間 XML 數據文件的制作過程有了相當的提速，現在這個過程在整個文檔生成過程中所占的時間比例已經很小了。
• 頁面制作的時間也減少了 20% ~ 50%。
• 內存占用顯著降低了。
• 命名空間層次結構頁面的制作過程，得到了改進，不再擔心性能或穩定性問題了。因此，文檔引擎總是制作命名空間層次結構頁。

程序集加載
　程序集的加載方法有了不少改進。

• 程序集改變時，GUI 程序不需要重新啟動就能反映更新。
• 大多數程序集可以從網絡共享地址加載。但是，因為 .NET Framework 的安全限制，由托管 C++ 生成的程序集必須在本地磁盤中，不能從網絡共享地址中正常加載。
• 程序集的解析得到了改進，現在已經極少出錯了。

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

注意，盡管 NDoc 支持多種字符集，但 NDoc 生成的代碼文檔的各個標題、及 NDoc 的界面、提示消息等文本，在 NDoc 1.3 中還未實現多語言顯示。

NDoc 并行運行能力
　多個 NDoc 實例現在可以同時并行運行。先前的文件鎖定等問題已經得到解決。

用戶界面

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

XML 文檔標記
　新標記

增強的標記

配置
　新配置項
　NDoc 1.3 加入了下面的通用配置項:

刪除的配置項
　NDoc 1.3 刪除了下面的配置項:

MSDN 文檔引擎
　新配置項
　NDoc 1.3 為 MSDN 文檔引擎加入了下面的配置項:

刪除的配置項
　NDoc 1.3 刪除了下面的配置項:

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

HTML Help 1 目錄樹中的圖標
　目錄樹中，不再出現問號(?)圖標。如果沒有指定，顯示為空白頁圖標。

運算符和類型轉換
　NDoc 1.3 修復了對運算符和類型轉換的處理 bug，頁面格式也更接近 .NET Framework SDK 類庫文檔。

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

• 在命名空間列表及類型的成員列表中，將為它們顯示紅色的“已過時。”
• 在類型概述頁/成員頁中，將為它們添加紅色的“注意：此成員現已過時。”

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

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

NDoc 1.3 的已知問題和限制

開始之前，您需要準備以下工具，它們可以從網絡中獲得。

HTML Help 1 編譯器
　HTML Help 1 文件，也就是 CHM 文件，是很常見的應用程序幫助文件格式，在 Visual Studio .NET 發布之前，MSDN 一直采用的就是 HTML Help 1 格式。

如果您準備創建 HTML Help 1 (*.CHM)文件，請確認您已經安裝好 Microsoft's HTML Help Workshop。此下載安裝包已包含必需的 HTML Help 1 編譯器。

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

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

Latex 編譯器
　如果您準備使用 LaTeX 文檔引擎創建 dvi 或 pdf 文件，您需要下載并安裝一個 LaTeX 系統，比如免費的 MikTeX。

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

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

H2Reg 許可您將它包含進部署安裝包中，它可以用來注冊 Microsoft Help 2 命名空間和幫助標題等。H2Reg 使用 INI 文件描述要部署的幫助文檔結構。NDoc 創建符合 H2Reg 需要的 INI 文件，指示它進行命名空間的注冊工作。

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

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

打開項目的“屬性”對話框，

找到程序集名稱

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

設置 XML 文檔文件配置

現在，每次使用 VS.NET 編譯您的程序集，都會自動從源代碼中提取所有的 XML 注釋，生成 XML 文檔文件。

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

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

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

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

比如如下的代碼:

把光標移動到 MyClass 構造函數的上面一空行，敲 '/' 鍵三次，VS.NET 自動創建一個 summary XML 文檔塊:

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

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

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

NDoc 支持擴充的標記和語法。某些標記只能用于特定的類型（類，結構，委托，接口，枚舉）或成員（字段，屬性，方法，事件等），請參見標記用法。

NDoc 將標記區分為三類: Section 標記，Block 標記，Inline 標記。

Section 標記
　Section 標記用于定義不同的代碼文檔的區域。它們都是頂級標記，Block 標記、Inline 標記都應包含在某個 Section 標記的內部。（除非自定義了擴展 XSLT 轉換，否則，在 Section 標記外部的 Block 標記或 Inline 標記都被忽略。）

Block 標記
　Block 標記用于 Section 標記的內部，它們將顯示在單獨的行中。

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

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

如果類型或成員具有以下屬性，NDoc 將顯示相應的特殊樣式，使文檔看起來更加專業。

新建 NDoc 項目和添加程序集
　如果您使用 Visual Studio.NET 開發工具，那么最簡單的方法就是點擊工具條中的“從 Visual Studio .NET 解決方案新建 NDoc 項目...”按鈕。

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

　編譯配置選擇對話框

“確定”之后，NDoc 項目設計器將自動生成一個新的 NDoc 項目，其中已包含解決方案中各個項目生成的程序集和相應的 XML 文檔。

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

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

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

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

NDoc 1.3 中，新增了 MSDN 2003 文檔引擎，在保留 MSDN 文檔引擎的特點之外，向接近 .NET Framework SDK 類庫文檔的方向又前進了一大步：加入了語言選擇器等特色功能。

NDoc 文檔引擎

所有的文檔引擎都共享一些配置項，比如要輸出哪些類型/不輸出哪些類型等；每種文檔引擎都會有一些額外的配置項，用于特定的配置。

更多的細節請參看文檔引擎。

生成代碼文檔
　選擇好文檔引擎，并做好相應的配置。您就可以點擊“生成”按鈕讓 NDoc 創建您需要的代碼文檔了。設計器下方的“輸出”窗口中將顯示文檔制作中的消息，狀態條上的進度條指示生成的整體進度。

NDoc 生成進度

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

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

NDoc 項目設計器

新建 NDoc 項目的工作可以很簡單：選擇要輸出代碼文檔的程序集、相應的 XML 文檔、選擇一個文檔引擎并做好配置參數。

命名空間摘要
　標準的 C# 注釋 XML 文檔中，沒有提供任何標記為命名空間提供“summary”文檔。NDoc 提供了兩種途徑允許您為命名空間提供“summary”文檔。一種是通過在您的代碼加入特定的類，并對 NDoc 文檔引擎作相應配置（請參見 NDoc 文檔引擎 中關于 UseNamespaceDocSummaries 配置項的說明）。另一種途徑是通過項目設計器指定各命名空間的摘要文檔。

在項目設計器中，單擊“命名空間摘要”按鈕，在彈出的“編輯命名空間摘要”對話框中，給每個命名空間填寫摘要文檔。

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

編輯命名空間摘要對話框

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

設計器中配置項以類別排列，并且，選中某一配置項時會顯示一小段提示文本，說明該配置項的用途和用法。這些都將幫助您快速掌握這些文檔引擎的使用方法。

關于完整的文檔引擎列表，及其配置項，請參見 NDoc 文檔引擎。

選項

概述
　NDoc 不僅提供了 GUI 的界面，也同時提供了命令行工具(NDocConsole.exe)，為和其他開發工具集成提供了方便。
　
　語法
　NDoc 命令行使用簡單的“name-value 對”語法來指定相應的配置項。每個選項前用一個短線，如：-name=value，短線和等號周圍不要有空格。下面語法敘述中，中括號的部分是可選的。路徑中如果包含有空格，則需要用引號(")括起來。
　用法 1

?

注釋:

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

用法 2

注釋:

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

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

• documenter: 要使用的文檔引擎的名稱。注意此項區分大小寫。
  缺省時，將使用 MSDN 文檔引擎。
• project: 您可以使用 NDoc GUI 界面保存一個 NDoc 項目文件，然后設置給此參數。
• verbose: 顯示文檔生成進度的輸出消息。

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

• help: 顯示命令行幫助信息。
  如果文檔引擎參數沒有指定，顯示 NDoc 命令行的基本語法。
• 文檔引擎: 顯示此文檔引擎的幫助信息（如：可用的配置參數項等）。注意此項區分大小寫。
  如果引擎參數沒有指定，顯示此文檔引擎可用的配置參數列表。
• 引擎參數: 顯示文檔引擎的某配置參數的信息，如描述、默認值。若參數為枚舉類型，還會列出可用的枚舉值（使用時注意區分大小寫）。

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

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

命名空間摘要 XML 文檔的語法

配置 NAnt(暫無)

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

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

if $(ConfigurationName) == Release
　因為直接在生成事件窗口中正確書寫 NDoc 命令行命令及相關參數、很困難也很容易出現錯誤，因此您可以將命令寫在一個批處理 .bat 文件中，而在項目的生成后事件中引用這個批處理文件(如下圖)，這樣比較容易書寫和維護。

Calling a batch file from the post-build event

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

關于 NDoc.bat 中的寫法，您可以參考下面的命名行（它對應于上面圖中的生成后事件命令）：

IF NOT %1 == Release GOTO end

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

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

其他開發工具的配置
　大多數開發工具都有運行命令行程序的選項，這些開發工具都可以使用 NDoc 命令行來實現代碼文檔的自動生成。每種開發工具的配置方法可能不同，但思路都很類似上面關于 VS.NET 中的想法。

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

• VS.NET
• MSDN
• MSDN 2003
• XML
• JavaDoc
• LinearHtml
• LaTeX
  NDoc 的設計具有很強的可擴展性，您可以自己創作輸出特定格式文檔的、新的文檔引擎。

代碼文檔的制作一般分作兩大環節:

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

通用的配置

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

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

<MSHelp:link

keywords="frlrfSystemVoidClassTopic"

indexMoniker="!DefaultAssociativeIndex"

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

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

每個頁面頭部的嵌入 XML 數據島中都包含若干 Keywords，您可以在 .NET Framework SDK 類庫文檔中查看 System.Void 頁面中，包含如下的一行:

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

這個 frlrfSystemVoidMembersTopic 就是在 .NET Framework SDK 類庫文檔中，用 DefaultAssociativeIndex 類型的“索引”中的 keyword。

鏈接到 .NET Framework SDK 類庫文檔
　指向到 .NET Framework SDK 類庫文檔的超鏈接，不需要您費心，NDoc 已經可以做的很好。您盡管從 .NET Framework 的基類型繼承、創作您的子類型，或者使用 <see> 等標記加入這些鏈接，NDoc 自動處理這些關于 XLinks 的事情。

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

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

<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 的 一個實例:

<?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 命名空間的類型/成員的鏈接，將被指向 ms-help://MS.NETFrameworkSDKv1.1.CHS 幫助文檔命名空間。

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

與 Visual Studio .NET IDE 的集成

　.NET Framework SDK 類庫文檔的每一個頁面的頭部都有一個嵌入的 XML 數據島。在 Microsoft 文檔資源管理器中，這些 XML 數據島用于創建索引，鏈接幫助主題，查找關鍵字，篩選幫助主題，以及很多其他功能。Visual Studio .NET IDE 中的“動態幫助”功能也依賴于這些嵌入的 XML 數據。以下是一個 XML 數據島示例：

<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 文檔引擎同樣創建這樣的 XML 數據島，以提高和 Microsoft 文檔資源管理器以及 VS.NET IDE 的集成性。

要求

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

Help Title 必須存在于一個幫助集合中。

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

只有幫助集合才能被集成到 VS.NET 的幫助系統中。

幫助集合必須在每臺機器上注冊后才能被訪問。

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

因為這個原因，幫助集合必須在安裝時注冊到每臺客戶端機器中，否則將無法訪問得到。

已注冊的幫助集合可以被“plugged-in”進 VS.NET 合并文檔集合。

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

還很糊涂？

　Microsoft Help 2 確實是一套復雜的技術。更深入的信息請查閱 VSHIK 文檔。網站 helpware.net 提供了很多有關 Microsoft Help 2 的有用資料和教程。HelpWare 還提供了一個名為 FAR 的共享軟件，它更證明了 Microsoft Help 2 幫助系統的潛力。

VS.NET 文檔引擎使用了幾個配置項，意在簡化整個過程。

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

然后，您需要指定 CollectionNamespace，幫助集合的命名空間名稱。不要使用空格、漢字等 URI 中不允許的字符。建議您設法讓這個命名空間名稱不容易重復，比如以您的公司名開始，等等。

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

篩選器

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

默認的一些篩選器定義如下:

將您的幫助集合加入上面這些篩選器的搜索范圍，可以很簡單的指定文檔引擎的 DocSetList 配置項。它是一個逗號分隔的字符串，每一項最終都被寫成 XML 數據島中的一行 DocSet 值。當用戶使用這些篩選器時，如果您的幫助頁面 XML 數據島中具有特定的 DocSet 值，您的幫助文檔就會被包括在搜索范圍中。

NDoc 默認將 HtmlHelpName 作為一行 DocSet 值寫入每頁的 XML 數據島。您不需要通過 DocSetList 重復定義它。

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

部署 Microsoft Help 2

　Microsoft Help 2 幫助系統維護一個注冊表(不要和 Windows 注冊表混淆)，保存當前機器中所有已安裝的幫助集合。注冊表保存了所有的幫助集合，每個幫助集合中包含的 Help Titles，幫助集合間的嵌套關系等。

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

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

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

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

下面是完整的步驟:

注意: 先執行 H2Reg，再刪除相應的幫助文件和 INI 文件。

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

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

配置
　所有文檔引擎都具有一些 通用的配置項。

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

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

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

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

請根據您的具體情況進行選擇具體采用哪種方式。

另外，RootPageFileName 指定 CHM 打開時的第一個頁面文件，這個頁面可以是 NDoc 生成的文件，也可以是通過上述兩種方式附加進去的某 HTML 文件。

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

配置
　所有文檔引擎都具有一些 通用的配置項。

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

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

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

請根據您的具體情況進行選擇具體采用哪種方式。

另外，RootPageFileName 指定 CHM 打開時的第一個頁面文件，這個頁面可以是 NDoc 生成的文件，也可以是通過上述兩種方式附加進去的某 HTML 文件。
　
　 概述
　XML 文檔引擎是 NDoc 中最簡單的文檔引擎，它直接輸出 NDoc 生成的中間 XML 文件。主要幫助開發人員調試 NDoc 擴展 XSLT 轉換，以及制作新的自定義文檔引擎。

請參見 NDoc 可擴展性 和 實現一個新的文檔引擎。

配置
　所有文檔引擎都具有一些 通用的配置項。

概述
　JavaDoc 文檔引擎用于創建類似 JavaDoc (Java 社區中，自動創建代碼文檔的工具) 布局和格式的 HTML 代碼文檔。

因為缺少足夠的關注度，此文檔引擎的開發并不活躍。 如果您有興趣進一步完善此文檔引擎，請聯絡 NDoc 項目管理員。

配置
　所有文檔引擎都具有一些 通用的配置項。

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

配置
　所有文檔引擎都具有一些 通用的配置項。

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

您需要安裝一個 LaTeX 編譯器，比如免費的 MiKTeX。關于 LaTeX 的中文支持問題，請參見 CTeX: 中文 TeX 網站 中的相關內容。

配置
　所有文檔引擎都具有一些 通用的配置項。

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

NDoc 支持擴充的標記和語法。某些標記只能用于特定的類型（類，結構，委托，接口，枚舉）或成員（字段，屬性，方法，事件等），請參見標記用法。

NDoc 將標記區分為三類: Section 標記，Block 標記，Inline 標記。

Section 標記
　Section 標記用于定義不同的代碼文檔的區域。它們都是頂級標記，Block 標記、Inline 標記都應包含在某個 Section 標記的內部。（除非自定義了擴展 XSLT 轉換，否則，在 Section 標記外部的 Block 標記或 Inline 標記都被忽略。）

Block 標記
　Block 標記用于 Section 標記的內部，它們將顯示在單獨的行中。

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

下面的表格顯示了各 block 標記的有效性。

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

<c>text</c>
　其中:

text
　要標記為代碼樣式的文本。
　應用于
　可用于其他標記內部。

備注
　如果需要標記多行的代碼塊，請使用 <code> 標記。

示例
　[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> 標記指示將其內部的文本表示為代碼樣式，Block 標記，用于表示多行的代碼塊。

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

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

備注
　使用 lang 屬性表示語言選擇器，標準的語言有: Visual Basic, C#, C++ 及 JScript。若代碼塊適用于多種語言，則用逗號隔開，比如“Visual Basic, C#, C++”。

escaped 為 true 時，其內部所有其他標記都被轉義為代碼塊的一部分。

注意 content 內容必須是格式完好的 XML 注釋。否則整個注釋塊可能被忽略或出錯!!!

示例
　下面示例中，因為 escaped="true"，因此直接寫入了要作為代碼塊的 XML 內容。 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> 標記用于說明被標記的方法可能引發的事件。Section 標記。

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

cref = "member"
　表示可能引發的事件。書寫時，如果可能引發的事件是同一類型的事件，member 可以直接寫事件名稱（注意大小寫）；如果是其他類型的，建議您寫該事件的完全限定名稱。C# 編譯器將檢查該事件是否存在。在輸出的 XML 文檔文件中，C# 編譯器會自動轉換簡寫的 member 為完全限定名稱。
　description
　附加的說明，比如在什么情況下引發該事件。
　應用于
　方法成員。

備注

示例

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

<example>description</example>
其中:

description
示例及其說明。
應用于
所有的類型及成員。

備注
此標記經常和 <code> 標記聯用。

示例
[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> 標記用于說明一個成員可能拋出的異常。

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

cref = "member"
表示可能拋出的異常類型。書寫時，如果可能拋出的異常是同一命名空間下的異常類型，member 可以直接寫異常名稱（注意大小寫）；如果是其他命名空間的，建議您寫該異常類型的完全限定名稱。C# 編譯器將檢查該異常是否存在。在輸出的 XML 文檔文件中，C# 編譯器會自動轉換簡寫的 member 為完全限定名稱。
description
說明信息，比如在什么情況下拋出該異常。
應用于
屬性, 方法, 事件, 運算符, 類型轉換

備注

示例
[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/> 標記指示 NDoc 文檔引擎將被標記的類型/成員排除在代碼文檔之外。

<exclude/>
應用于
所有的類型及成員。

備注
與文檔引擎的“可見性”配置不符的，以 exclude 優先。

示例
請參見

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

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

filename
包含 XML 文檔注釋的文件名。該文件名可包含路徑。將 filename 括在單引號中 (' ')。
tagpath
filename 中指向標記名的標記路徑（使用 XPath 語法）。將此路徑括在單引號中 (' ')。
name
注釋前邊的標記中的名稱說明符；名稱具有一個 id。
id
位于注釋之前的標記的 ID。將此 ID 括在雙引號中 (" ")。
應用于
所有的類型及成員。

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

<include> 標記使用 XML XPath 語法。有關自定義 <include> 使用的方法，請參見 XPath 文檔。

示例
以下是一個多文件示例。第一個文件使用 <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()
{
}
}
第二個文件 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> 標記表示一個列表(數字列表或符號列表)，或一個表格，或一個定義表。Block 標記。

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

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

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

<item> 塊表示列表中的一項。item 包含子元素 term 和 description。對 bullet 和 number 列表，term 無效也不需要寫。對 table 表，可以沒有 term，只寫 description。對 definition 表，term 和 description 都應該有。

列表可以根據需要包含多個 <item> 塊。

示例

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

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

其中:

description
注意事項。
應用于
可用于其他標記內部。

備注
caution 將顯示為“警告”，inheritinfo 將顯示為“對繼承者的說明”，implementnotes 將顯示為“對實施者的說明”。

示例

　 <overloads> 標記為“重載列表”頁面提供文檔。

簡單語法
<overloads>
summary_description
</overloads>

復合語法
<overloads>
<summary>summary_description</summary>
[<remarks>remarks_description</remarks>]
[<example>examples_description</example>]
</overloads>

應用于
屬性, 方法, 事件, 運算符。

備注
只需在重載成員的第一個成員前面書寫此區域即可。

此標記有兩種形式:

簡單的形式，直接在 overload 中寫文本，這些文本被處理為“重載列表”頁面的摘要。沒有備注、示例等區域。
復雜的形式，在 overload 內部，包含 summary, remarks, example 等標記分別表示“重載列表”頁面的摘要、備注、示例等。
示例

<para> 標記表示一個段落。

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

lang="language" [NDoc 擴充]
表示語言選擇器，指示此段落僅對某種編程語言有效。(可選)
content
段落文本。
應用于
可用于其他標記內部。

備注
此標記經常用于 <summary>, <remarks>, 及 <returns> 等標記內部。

使用 lang 屬性表示語言選擇器，標準的語言有: Visual Basic, C#, C++ 及 JScript。若代碼塊適用于多種語言，則用逗號隔開，比如“Visual Basic, C#, C++”。

示例
請參見 <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> 標記引用一個參數，將以代碼樣式表示該參數名稱。

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

name
參數的名稱。
應用于
可用于其他標記內部。

備注
示例
[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> 標記說明訪問某成員所必需的 .NET Framework 安全性 CodeAccessPermission。

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

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

備注
System.Security.PermissionSet 使您得以指定對成員的訪問。

示例
[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> 標記將類型/成員標記為“預發布”。

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

description
對“預發布”的說明文本。(可選)
應用于
所有的類型及成員。

備注
若沒有指定 description，則以紅色顯示默認的文本: “[此文檔為預發布版本，在未來版本中有可能改變。]”

如果需要把全部類型/成員都標記為“預發布”，請使用文檔引擎的 Preliminary 配置項。

示例
[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> 標記表示對類型或成員的“備注”。

<remarks>description</remarks>
其中:

description
對類型/成員的“備注”。
應用于
所有的類型及成員。

備注
<remarks> 標記用于對 <summary> 摘要信息的補充。.

示例
[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> 標記用于說明方法的返回值。

<returns>description</returns>
其中:

description
對方法的返回值的說明。
應用于
方法。

備注
示例
[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> 標記用于在行文中添加一個超鏈接。

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

label
超鏈接的顯示文本。
cref = "member"
表示要鏈接到的類型(成員)。書寫時，如果要鏈接到的類型(成員)是同一命名空間(類型)中的類型(成員)，member 可以直接寫它的名稱（注意大小寫）；如果是其他命名空間(類型)的，建議您寫該類型(成員)的完全限定名稱。C# 編譯器將檢查該類型(成員)是否存在。在輸出的 XML 文檔文件中，C# 編譯器會自動轉換簡寫的 member 為完全限定名稱。
href = "URL" [NDoc 擴充]
一個網絡 URL 地址。
langword [NDoc 擴充]
將會被當作 .NET 關鍵字粗體顯示。如果 langword 是下面備注中的表格里的某個關鍵字，還將會被替換為相應的說明文本。
應用于
可用于其他標記內部。

備注
　使用 <seealso> 標記將超鏈接加入到頁面的“請參見”區域。

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

可識別的 langword
　如果 langword 為下表中的關鍵字之一，則會顯示右側相應的說明文本。

示例
　請參見 <summary> 中的示例。

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

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

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

備注
使用 <see> 標記在行文中添加超鏈接。

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

示例
請參見 <summary> 中的示例。

<summary> 標記用于對類型或成員的摘要說明。

<summary>description</summary>
其中:

description
對類型或成員的摘要說明。
應用于
所有的類型及成員。

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

<remarks> 標記用于更詳細的說明。

示例
[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> 標記用于說明類型在多線程環境中是否安全。
<threadsafety static="true|false" instance="true|false"/>
其中:

static="true|false"
指示類型的靜態成員在多線程環境中是否是安全的。
instance="true|false"
指示類型的實例成員在多線程環境中是否是安全的。
應用于
類, 結構。

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

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

<value> 標記用于說明屬性的值。

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

property-description
對屬性值的說明。
應用于
屬性。

備注
按照約定，總是應該為屬性書寫 <value> 標記。

示例
[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 可擴展性
MSDN, MSDN 2003 和 VS.NET 文檔引擎都支持一個可擴展的模型，允許您定義自己專有的標記，并指定它們在代碼文檔中呈現的樣式。您或許已經知道，這些文檔引擎都使用 XSLT 轉換，將 NDoc 中間 XML 數據文件轉換為目標 HTML 格式。NDoc 標記的可擴展性也依賴于此，您可以通過自定義的 XSLT 轉換文件加入您自定義的標記。（建議，您需要事先了解一些 XSLT 轉換的知識，并分析 XML 文檔引擎生成的 NDoc 中間 XML 數據文件中的 XML 格式，經過足夠的測試，以調試您自己的擴展 XSLT 轉換。）

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

[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 文檔中，您可以找到這些自定義的標記。

接下來，創建您的 XSLT 轉換模板，控制那些自定義標記的輸出位置和樣式:

<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>

您應該確認 XSLT 標記的完整和語法的正確，注意 XSLT namespace 是必須的。

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

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

什么是 mode 呢？mode 用于指定該內容將顯示于文檔的哪些區域。NDoc 擴展的自定義標記可以是以下兩類:

Section 標記 - 塊標記，將顯示于文檔的某個區域。為 section 標記編寫 template 時，mode 必須是預定義的可用 Section 的列表中的一個。
Inline 標記 - 將和其他注釋文本夾雜在一起。為 inline 標記編寫 template 時，mode 必須是 "slashdoc"。
如果您準備編寫匹配一些泛型 XPath 查詢，如 node(), text(), *, 或 @*，您應當給該 template 指定一個名為 priority、值大于 0.5 的屬性，用您編寫的 template 替換 NDoc 默認的轉換模板。

請注意: XSLT 是大小寫敏感的，match 查詢模式，以及 mode 值都必須使用正確的大小寫，否則將被忽略。

最后，為 MSDN 或 VS.NET 文檔引擎設置 ExtensibilityStylesheet 配置，指向您創作好的 XSLT 轉換文件。然后使用 NDoc 生成代碼文檔，您將看到已經按照您編寫的 template 規則執行了相應轉換。

一張屏幕截圖:

輸出示例

可用 Section 的列表
下面列出了所有可用 section 的清單，它們用于 NDoc 擴展 XSLT 轉換模板中 mode 屬性的值，指示該標記將顯示在代碼文檔中的區域。

實現一個新的文檔引擎
　實現一個新的文檔引擎至少需要編寫兩個類:

一個從 NDoc.Core.DocumenterBase 繼承而來的類

一個從 NDoc.Core.DocumenterConfigBase 繼承而來的類

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

DocumenterBase 是文檔引擎的基類。文檔引擎的工作模式是，第一步生成 NDoc 中間 XML 數據文件，第二步由各文檔引擎將中間 XML 數據文件、分別轉換成所需的最終文檔格式。此基類完成了第一步的工作，您編寫的子類只需完成第二個步驟。

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

實現 Build 方法時, 可以調用基類的 MergeXML 方法，它完成第一步的 NDoc 中間 XML 數據文件的合并和制作。

使用 XML 文檔引擎 可以導出一個 NDoc 中間 XML 數據文件的樣例。您可以通過分析它，調試您的自定義轉換代碼或 XSLT 轉換定義。使用 UseNDocXmlFile 配置項，可以節省您的調試時間。

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

NDoc.Documenter.<NAME>.dll

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

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

為 NDoc 貢獻代碼
您可以有很多種選擇，為 NDoc 的開發做出有益的貢獻。

• 加入 ndoc-users 郵件列表 是最簡單的方式、和其他用戶分享您的使用心得體會和經驗。
• 如果您發現了 bug，或者有一些不錯的新功能建議，請使用 NDoc tracker database， 讓我們了解您的發現和想法。
• 如果您有更多空閑的時間，希望成為 NDoc 開發組的成員、和我們一起實現那些 new features 或者修復那些已知的 bugs，請通過NDoc SourceForge 站點聯絡項目的負責人、管理員，我們會幫助您開始工作。我們歡迎越來越多的人們加入 NDoc 隊伍！
• 感謝您使用 NDoc！

NDoc 用戶郵件列表
　您也可以搜索 ndoc-users 郵件列表的存檔郵件，或者發送問題到這個郵件列表。

NDoc 跟蹤數據庫
　如果通過以上途徑還是沒有找到您要的答案，您可以嘗試 NDoc 在 SourceForge.net 維護的 Tracker database。

• 提交一個支持請求(support request)
• 提交 Bug 報告
• 提交新功能建議

介紹 NDoc 的文章
　網絡中還有很多不錯的 NDoc 介紹文章，下面有些文章發布時間很早，有些鏈接已經失效了。

• [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?