關于 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 文檔標記

新標記

標記

說明

Directs NDoc to exclude the tagged type or

member from the documentation.

The tag overrides all visibility options.

Marks the documentation of a type or member

as preliminary.

This tag can include text and block tags like in

order to put a custom warning into your help topics about preliminary

items.

If the tag is empty, preliminary topics will include the default

message:

[This is preliminary documentation and subject to change.]

It is also possible to mark an entire help project as preliminary

using the Preliminary project setting.

增強的標記

標記

說明

"lang" attribute

No more to prevent indent

"Escaped" attribute

langword

配置

新配置項

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

配置項

說明

文檔主要配置

CleanIntermediates

是否在文檔成功生成后，刪除中間文件。

比如 MSDN 和 VS.NET 文檔引擎會編譯為單一文件，它們的中間文件包括所有編譯前的網頁、HTML Help 項目文件等。

FeedbackEmailAddress

用戶反饋接收 Email 地址。將在輸出的代碼文檔每頁的底部添加放置指向此 Email

地址的超鏈接。

Preliminary

若此項為真，文檔引擎將在每個頁面中添加紅色的消息“[此文檔為預發布版本，在未來版本中有可能改變。]”。

SdkDocVersion

指示文檔引擎應將 .NET Framework 標準類庫中包含的類型的超鏈接指向哪個版本的

.NET Framework SDK。

SdkDocLanguage

指示文檔引擎應將 .NET Framework 標準類庫中包含的類型的超鏈接指向哪種本地化語言版本的

.NET Framework SDK。

屬性(attribute)的輸出

DocumentInheritedAttributes

是否輸出從基類中繼承而來的屬性(attribute)。如果 DocumentAttributes

= false，則此配置被忽略。

輸出過濾

DocumentedInheritedMembers

如何輸出繼承的成員：可選擇不輸出、只輸出繼承的實例成員或者是全部繼承成員都輸出。

它有三個選項: None

不輸出繼承的成員。

Instance

只輸出繼承的實例成員。(默認選項)

InstanceAndStatic

輸出全部繼承的實例和靜態成員。

DocumentInheritedFrameworkMembers

是否輸出從 .NET Framework 中的類、結構等繼承下來的成員。(默認為輸出)

注意: 如果 DocumentInheritedMembers 為 None, 此配置被忽略。

DocumentExplicitInterfaceImplementations

是否輸出顯式實現的接口成員。(默認為否)

DocumentSealedProtected

是否輸出密封類 (sealed, VB.NET 中為 NotInheritable)

的 protected 成員。(默認為否)

注意: 如果 DocumentProtected 為 false，則忽略此項配置。

SkipNamespacesWithoutSummaries

是否跳過缺少概述信息的命名空間。(默認為否)

刪除的配置項

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

配置項

說明

GetExternalSumeries

NDoc 中間 XML 數據文件制作的性能有了相當的改進。因此，總是嘗試為從 .NET

Framework 繼承而來的成員查找摘要信息。

IncludeNamespaceHierarchy

命名空間層次結構頁面的制作過程，得到了改進，不再擔心性能或穩定性問題了。因此，文檔引擎總是制作命名空間層次結構頁。

MSDN 文檔引擎

新配置項

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

配置項

說明

文檔主要配置

BinaryToc

是否以二進制方式創建目錄樹文件。這將顯著提高大尺寸 CHM 文件的打開速度。

默認此項被設置為 true。但啟用此配置項，有一些強制的限制必須滿足。如果您遇到問題，可以嘗試關閉此功能。更多細節請查看

HTML Help Workshop 的文檔。

Title

此文本將顯示在每個頁面的左上角，一般填寫類庫的名稱比較合適。

擴展性

ExtensibilityStylesheet

用戶自定義的 NDoc 擴展 XSLT 轉換文件，用于轉換用戶自定義的特殊標記。請參見

NDoc 可擴展性。

HTML Help 選項

AdditionalContentResourceDirectory

頁面中涉及到的資源文件(如圖片等)所在的目錄。此目錄及其子目錄中的所有文件，將以原有的目錄結構包含進

HTML Help 項目中，使用相對路徑的超鏈接不需要做大的調整。

注意: 此文件夾中第一層次的文件，和 NDoc 生成的 HTML 文件、以及通過 FilesToInclude 包含進來的文件，將處在同一層次上，請依次類推其他文件的相對

URL。

LangID

HTML Help 文件的 LangID 設置。中文版默認為 2052。

刪除的配置項

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

配置項

說明

SortTOCByNamespace

在 NDoc 1.3 中，各命名空間對應的目錄結點總是按字母排序。

SplitTOCs

在老的 MSDN 文檔引擎中，此配置項用于克服一些限制。新版本中繞開了它。

DefaultTOC

CHM 目錄中第一個命名空間結點總是被默認被選中。

LinkToSdkDocVersion

此配置項現在區分為 SdkDocVersion 和 SdkDocLanguage，且提升為所有文檔引擎的通用配置項。

NDoc 1.3 仍然會嘗試解析此配置，如果您重新保存，NDoc GUI 會用新的配置項改寫。

改進的超鏈接邏輯

將形成一個指向另一個類型/成員的文檔的鏈接。在 NDoc 1.3 中，如果一個 HTML 頁中出現了多個指向同一個類型/成員的文檔的

，則只轉換第一個為超鏈接，其余的不表示為超鏈接、只顯示為粗體。這將使頁面不至于太雜亂。

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 的已知問題和限制

事項

說明

特別長的類型名稱

NDoc 為每一個主題自動在硬盤上創建一個 HTML 文件。目前，文件名是根據完全限定名生成的。如果某類型/成員的完全限定名

(命名空間 + 類型 + 成員名) 的總字符數超過 _MAX_FNAME (256 字符)，NDoc 將無法創建這樣的文件，因為操作系統不支持如此多字符的文件名。另外，文件所在完整路徑的字符也不能超過

_MAX_PATH (260 字符)。

如果完全限定名的字符數在

200 字符左右，那么您可能需要將 OutputDirectory 配置為一個靠近根目錄的位置，這樣可以避免文件的完整路徑超出

260 字符。

但還沒有關于文件名超出 256 字符的解決方法。

在未來某版本的 NDoc 中，我們會嘗試解決此問題。

大小寫敏感問題

文件名不是大小寫敏感的，因此當 MSDN 文檔引擎或者 JavaDoc

文檔引擎創建 HTML 文件時，如果某些類型或成員只是在大小寫上不一樣，就會出現問題。

請嘗試避免出現這種情況。(例如：公共屬性為

Thing，私有字段為 _thing, 避免出現Thing 和 thing 并行。當然，如果不輸出私有字段，并行也沒有問題。只是說準備輸出的類型/成員不要出現這種情況。)

在未來某版本的 NDoc 中，我們會嘗試解決此問題。

StrongNameIdentityPermissionAttribute

標記有 StrongNameIdentityPermissionAttribute

屬性的程序集，需要有特殊的密鑰才能被讀取。NDoc 嘗試為這樣的程序集生成代碼文檔時，會拋出異常。

您可以考慮使用“條件編譯”(#if...)方式為 NDoc 準備沒有添加該屬性的編譯版本。

Compact Framework 不兼容

為 .NET Compact Framework 編譯的程序集，當添加到

NDoc 項目中時，NDoc GUI 程序可能拋出異常。尤其是當該程序集引用了 Microsoft.WindowsCE.Forms

或 SqlServerCe 時，更是如此。

還沒有找到此問題的解決方法。

在未來某版本的 NDoc 中，我們會嘗試解決此問題。

本地化

NDoc 當前不支持本地化的文檔格式及 GUI 文本

在未來某版本的 NDoc 中，我們 *可能* 會嘗試解決此問題。

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

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 注釋越多，最終生成的代碼文檔越專業。程序集的使用者越能從中獲得幫助。

一般而言的最低要求，對于每一個公共類型，應該給它的所有公共的和受保護的成員添加

注釋，以描述該成員表示什么意義或者會做些什么動作。

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

注釋。

比如如下的代碼:

public class MyClass() {

public MyClass( string s ) { }

}

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

summary XML 文檔塊:

public class MyClass() {

///

///

///

///

public MyClass( string s ) { }

}

這種操作對于所有可以書寫 XML 注釋文檔的成員都有效。另外，在以 '///' 開頭的 XML

注釋行中，敲入 '

所支持的額外的標記，這些額外的標記，您需要手工敲入。

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 標記都被忽略。)

標記

說明

[NDoc 擴充]

對某個成員可能引發的事件的說明。

“示例”，幫助類庫使用者理解類型/成員使用方法的示例代碼。

對某個成員可以拋出的異常的說明。

[NDoc

擴充]

指示 NDoc 文檔引擎將被標記的類型/成員排除在代碼文檔之外。

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

將代碼文件外部的某 XML 文件中的一部分包含進代碼文件來。

[NDoc

擴充]

為“重載列表”頁面準備摘要、備注、示例等文檔內容。只需在重載成員的第一個成員前面書寫此區域即可。

標記有兩種形式:

簡單的形式，直接在 overload 中寫文本，這些文本被處理為“重載列表”頁面的摘要。沒有備注、示例等區域。

復雜的形式，在 overload 內部，包含 summary, remarks,

example 等標記分別表示“重載列表”頁面的摘要、備注、示例等。

示例:

///This method has two overloads.

///This overload just says hello.

public void SayHello() { ... }

///This one says hello to someone.

public void SayHello(string toSomeone) { ... }

成員的參數說明。

訪問某成員所必需的 .NET Framework 安全性 CodeAccessPermission。

[NDoc

擴充]

將某類型/成員標記為“預發布”。內部的文本被當作警告文本用紅色顯示，可以包含

表示多行文本。如果缺少內部文本，則顯示默認的警告文本: “[此文檔為預發布版本，在未來版本中有可能改變。]”。

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

“備注”，對 的進一步注解。

“返回值”。

向頁面的“請參見”區域添加一個鏈接。

請不要將此標記包含在

內部，它是一個頂級標記。

兩種可選的語法:

MSDN(CHS)

DataSet

“摘要”，對類型/成員的摘要說明。

[NDoc

擴充]

“線程安全”，說明類型在多線程環境中是否安全。

NDoc

提供 static 和 instance 兩個布爾的屬性，可以自動生成像 .NET Framework SDK 類庫文檔中那樣的標準文本。

threadsafety 標記內部可以包含額外的文本，會被顯示到標準文本的下方，說明額外的信息。例如:

/// The summary description

for SafeClass.

///

/// More information about using this class across

thread

///

public class SafeClass() { ... }

“屬性值”。

Block 標記

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

標記

說明

多行的代碼塊。

一個列表或表格。

[NDoc

擴充]

“注意”塊。

例如:

///

/// This is a note in the summary.

///

public class SomeClass() { ... }

將生成:

注意 This is a note in the summary.

表示一個段落。

Inline 標記

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

標記

說明

將內部文本格式化為代碼樣式，用于表示行文中提到的短小代碼片段。

加入指向方法參數的鏈接。

加入指向某個類型/成員或網絡 URL 的鏈接。

兩種可選的語法:

MSDN(CHS)

DataSet

其中 xxx 可以是 null, sealed, static, abstract 或 virtual。

NDoc 中的 MSDN 文檔引擎和 VS.NET 文檔引擎使用了一些

屬性 來控制代碼文檔中一些特殊樣式。

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

屬性

說明

ObsoleteAttribute

標記該類型或成員為“已過時。”

FlagsAttribute

指示可以將枚舉作為位域(即一組標志)處理，允許按位組合其成員值。

NDoc 將仿照 .NET Framework SDK 文檔中處理方式： 在該枚舉摘要下面顯示“此枚舉具有允許按位組合其成員值的 FlagsAttribute

屬性。”

在枚舉成員的列表中添加“值”列，顯示每個枚舉成員對應的枚舉值。

EditorBrowsableAttribute

使用此屬性(attribute)的成員將不顯示在 VS.NET 的屬性窗口、對象瀏覽器及智能感知等列表中，根據

NDoc 項目配置中的 EditorBrowsableFilter 配置，NDoc 可以將這部分被隱藏的成員排除在代碼文檔之外。

注：在 NDoc 1.3 中，我們推薦您使用 XML 文檔標記在代碼文檔中隱藏某些類型或成員。

AssemblyVersionAttribute

根據 NDoc 項目配置中的 AssemblyVersionInfo 配置，NDoc

可以在代碼文檔中包含通過 AssemblyVersionAttribute 屬性指定的程序集版本信息。

新建 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 文檔引擎。

選項

選項

說明

ShowProgressOnBuild

如果為真，在文檔生成動作啟動時，消息輸出窗口將自動顯示出來。

LoadLastProjectOnStartup

如果為真，每次啟動 NDoc 時將自動加載最后一次打開的項目文件。此配置和登陸的 Windows

用戶相關。

MRUSize

“最近的項目”列表中顯示的最大條目數。

HtmlHelpWorkshopLocation

HTML Help Workshop 軟件安裝路徑，即 HHC.exe 編譯器的所在目錄。僅對

MSDN 和 MSDN 2003 文檔引擎有效。

默認情況下，MSDN 和 MSDN 2003 文檔引擎會嘗試查找 HTML Help 1 編譯器的所在位置，但仍會出現無法定位的情況。這時，NDoc

會提示您無法找到 HHC.exe 編譯器，您需要設置此配置項解決問題。

此配置為機器級別的配置，在此機器上的任何 Windows 用戶都共享此配置。

概述

NDoc 不僅提供了 GUI 的界面，也同時提供了命令行工具(NDocConsole.exe)，為和其他開發工具集成提供了方便。

語法

NDoc 命令行使用簡單的“name-value 對”語法來指定相應的配置項。每個選項前用一個短線，如：-name=value，短線和等號周圍不要有空格。下面語法敘述中，中括號的部分是可選的。路徑中如果包含有空格，則需要用引號(")括起來。

用法 1

NDocConsole 程序集[,XML文檔]

[程序集[,XML文檔]]...

[[-referencepath=文件夾] [-referencepath=文件夾]...]

[-namespacesummaries=文件名]

[-documenter=文檔引擎]

[[-引擎參數=值] [-引擎參數=值]...]

[-verbose]

注釋:

程序集: 要生成文檔的完整路徑。

XML文檔: 對應的 XML 文檔(C# 編譯器 /doc 輸出的 XML 文檔)。

缺省時，將自動查找和程序集相同路徑、相同名稱，僅擴展名不同(.xml)的 XML 文件代替。

referencepath: 引用的第三方 dll 的搜索路徑。

namespacesummaries: 要使用的 命名空間摘要 XML 文檔 的完整路徑。

documenter: 要使用的文檔引擎的名稱。注意此項區分大小寫。

缺省時，將使用 MSDN 文檔引擎。

引擎參數: 文檔引擎的配置參數名稱，注意此項區分大小寫。

值: 給引擎參數設置的值。

verbose: 顯示文檔生成進度的輸出消息。

用法 2

NDocConsole -recurse=文件夾[,最大讀取深度]

[[-referencepath=文件夾] [-referencepath=文件夾]...]

[-namespacesummaries=文件名]

[-documenter=文檔引擎]

[[-引擎參數=值] [-引擎參數=值]...]

[-verbose]

注釋:

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 文檔的語法

name="My.NameSpace">My summary.

My other

summary.

...

配置 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 的設計具有很強的可擴展性，您可以自己創作輸出特定格式文檔的、新的文檔引擎。

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

將從程序集中通過反射發出讀取的類型/成員信息，和 /doc XML 文檔中的注釋文檔，合并在一起，即

NDoc 中間 XML 數據文件。

通過 XSLT 轉換將 NDoc 中間 XML 數據文件轉換為目標 HTML 格式。

您可以通過 XML 文檔引擎得到 NDoc 中間 XML 數據文件，經過分析和轉換，創作您自己的文檔引擎。

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

通用的配置

配置項

說明

(全局)

ReferencePaths

一組額外的程序集搜索路徑。

注意：這是一個 NDoc 項目級別的屬性，各文檔引擎共享此項配置。

文檔主要配置

AssemblyVersionInfo

如何輸出版本信息。

可選項為: None

不輸出版本信息。(默認選項)

AssemblyVersion

輸出標準 .NET 的版本號，即通過 AssemblyVersionAttribute

屬性設置的版本號。

AssemblyFileVersion

通過 AssemblyFileVersionAttribute 屬性指定的版本號。如果程序集需要安裝到

GAC，通過這種方式指定程序集的版本比較常見。

AutoDocumentConstructors

若此項為真，文檔引擎將為類型的默認構造函數(即不附帶參數的那個構造函數)添加默認的

summary 文檔。

AutoPropertyBackerSummaries

若此項為真，文檔引擎會把字段 _Length 或 length 視為屬性 'Length'

的輔助字段，在 _Length 或 length 缺少文檔信息時，自動為它添加 summary 信息(“屬性 Length

的輔助字段。”)。

CleanIntermediates

是否在文檔成功生成后，刪除中間文件。

比如 MSDN 和 VS.NET 文檔引擎會編譯為單一文件，它們的中間文件包括所有編譯前的網頁、HTML Help 項目文件等。

CopyrightHref

版權聲明文本的超鏈接地址。

CopyrightText

版權聲明文本，將被輸出到代碼文檔的每個頁面中。

FeedbackEmailAddress

用戶反饋接收 Email 地址。將在輸出的代碼文檔每頁的底部添加放置指向此 Email

地址的超鏈接。

Preliminary

若此項為真，文檔引擎將在每個頁面中添加紅色的消息“[此文檔為預發布版本，在未來版本中有可能改變。]”。

SdkDocLanguge

指示文檔引擎應將 .NET Framework 標準類庫中包含的類型的超鏈接指向哪種本地化語言版本的

.NET Framework SDK。

SdkDocVersion

指示文檔引擎應將 .NET Framework 標準類庫中包含的類型的超鏈接指向哪個版本的

.NET Framework SDK。

UseNamespaceDocSummaries

若此項為真，文檔引擎將在每個命名空間中查找一個名為 NamespaceDoc 的類，并將它的

summary 信息作為這個命名空間的 summary，這個類本身不會出現在最終的代碼文檔中。

如果需要，您可以使用 #if ... #endif，配合條件編譯常數，在最終 Release 程序集中排除 NamespaceDoc

類。

UseNDocXmlFile

主要用于調試用途，一般情況下請留空白。NDoc 會首先生成中間 XML 數據文件(可以使用

XML 文檔引擎得到)，然后通過 XLST 轉換為各種 HTML 格式。如果希望創作自定義的文檔引擎，可以將此選項配置為事先生成的一個

NDoc 中間 XML 數據文件，這樣將提高您的調試效率。

屬性(attribute)的輸出

DocumentAttributes

是否輸出類型和成員的屬性(attribute)。

DocumentedAttributes

屬性(attribute)輸出的過濾。當 DocumentAttributes

= true 時，此配置指示將輸出哪些屬性，其他屬性被過濾掉。

請使用編輯器生成，有效的格式應為：

',,|,,|(etc...)'

如果為空白，則輸出全部屬性。

DocumentInheritedAttributes

是否輸出從基類中繼承而來的屬性(attribute)。如果 DocumentAttributes

= false，則此配置被忽略。

ShowTypeIdInAttributes

是否在屬性(attribute)輸出時輸出 TypeId 值。如果 DocumentAttributes

= false，則此配置被忽略。

缺少文檔時的輸出

ShowMissingParams

缺少 參數文檔時，是否輸出紅色的提示文本。

ShowMissingRemarks

缺少 備注文檔時，是否輸出紅色的提示文本。

ShowMissingReturns

缺少 返回值文檔時，是否輸出紅色的提示文本。

ShowMissingSummaries

缺少 概述文檔時，是否輸出紅色的提示文本。

ShowMissingValues

缺少 屬性值文檔時，是否輸出紅色的提示文本。

XLinks

HTML Help 1 直接使用 HTML 標記表示超鏈接。Microsoft Help 2 引入了新的

XLinks 機制 (是微軟對 W3C XLinks 的一個實現)，來表示指向其他文檔集合的超鏈接。一個 XLink 很像 HTML

鏈接，但包含額外的元數據用于表示復雜的鏈接。Microsoft Help 2 使用 XLinks 不直接使用路徑/文件名，而根據在“索引”表中檢索特定的關鍵字查找。

NDoc 為指向 .NET Framework 類型/成員的鏈接(包括成員列表中指向基類型的鏈接、以及使用

標記加入的指向 .NET Framework 或第三方類庫中的類型/成員的顯式鏈接)，制作 XLinks

鏈接。下面是一個指向 System.Void 的示例 XLink:

上面 XLink 的三個屬性指示了查找這個幫助主題的方法。屬性 namespace 指示在哪個文檔命名空間中查找(每個幫助文檔集合都需要在機器中注冊一個唯一的命名空間，如上面的

ms-help://MS.NETFrameworkSDKv1.1.CHS 表示 .NET Framework SDK 類庫文檔的幫助文檔集合)。屬性

indexMoniker 指示使用哪種類型的“索引”(Microsoft Help 2 索引可以有很多類型，其中，DefaultAssociativeIndex

常用于創建幫助主題之間的關聯)。最后，keyword 指示要指向哪個幫助主題頁面。

每個頁面頭部的嵌入 XML 數據島中都包含若干 Keywords，您可以在 .NET Framework

SDK 類庫文檔中查看 System.Void 頁面中，包含如下的一行:

這個 frlrfSystemVoidMembersTopic 就是在 .NET Framework

SDK 類庫文檔中，用 DefaultAssociativeIndex 類型的“索引”中的 keyword。

鏈接到 .NET Framework SDK 類庫文檔

指向到 .NET Framework SDK 類庫文檔的超鏈接，不需要您費心，NDoc 已經可以做的很好。您盡管從 .NET

Framework 的基類型繼承、創作您的子類型，或者使用 等標記加入這些鏈接，NDoc 自動處理這些關于

XLinks 的事情。

鏈接到第三方類庫文檔

NDoc 允許您創建指向到第三方類庫文檔的超鏈接，不過也需要嚴格按照上面介紹的 XLinks 體制來做。首先找到該文檔集合的命名空間，和要指向的幫助主題

HTML 頁頭部中的 keyword，做好準備。(如果那個文檔集合也是用 NDoc 1.3 生成的，則頁面頭部的 XML 數據島已經按要求寫好了

keyword。)

因為 NDoc 只能找到子類型的父類型的名稱， 標記中最終 NDoc 看到的也只是要指向的類型/成員的完全名稱；NDoc

不知道這些類型/成員的文檔存在哪個文檔集合中。您需要告訴 NDoc：哪些類型/成員的幫助文檔在哪個文檔命名空間，而另一些類型/成員在另一個文檔命名空間，也就是各

.NET 類型/成員和 Microsoft Help 2 幫助文檔命名空間之間的映射關系。這就需要您指定 NamespaceMappingFile

了(請參見 VS.NET 2003 文檔引擎的 UseHelpNamespaceMappingFile 配置項)。NamespaceMappingFile

是一個 XML 文件，它必須符合 NamespaceMapping XSD 架構(請右擊“另存為...”)。

NamespaceMappingFile 的 一個實例:

上面的例子表示指向 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 數據島示例：

Value="kbWFC"/>

Value="kbManagedC"/>

Value="kbProfile2NETCF"/>

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

值常常被各個篩選器用于篩選幫助索引及搜索范圍。

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

Windows Client SDK, 　　Query:

"DocSet"="WCSDK"

.NET Framework, 　　　　Query: ("DocSet"="NETFramework"

OR "DocSet" = "NETFrameworkExtender") OR

(("DocSet"="C#" OR "DocSet"="Visual

Basic" OR "DocSet"="Visual C++" OR

"DocSet"="VBA" OR "DocSet"="VJ#"

OR "DocSet"="Visual Studio") AND "Technology"="ManagedCode")

Visual Studio 宏, 　　　Query: "DocSet" = "VSM"

OR "DocSet" = "NETFramework"

Visual Basic, 　　　　　Query: "DocSet" = "Visual

Basic" OR "DocSet" = "NETFramework"

OR "DocSet" = "NETFrameworkExtender" OR

"DocSet" = "DHTML" OR "DocSet"

= "XML" OR ("DocSet" = "kbmsdn"

AND "ProductVers" = "kbVBp700")

Visual C++, 　　　　　　Query: "DevLang" = "C"

OR "DevLang" = "C++" OR "Product"

= "VC" OR "DocSet" = "PSDK" OR

"DocSet" = "NETFramework" OR ("DocSet"

= "kbmsdn" AND "ProductVers" = "kbVC700")

Platform SDK, 　　　　　Query: "DocSet" = "PSDK"

(no filter), 　　　　　Query:

企業級服務器, 　　　　Query: "DocSet" = "NETEnterpriseServers"

OR "DocSet" = "SQL Server"

Internet 開發,　　　　Query: "DocSet" = "DHTML"

OR "DocSet" = "XML" OR "DevLang"

= "DHTML" OR "DevLang" = "HTML"

OR "DevLang" = "VBScript" OR "DevLang"

= "JScript" OR "DevLang" = "ASP"

OR "Technology" = "kbSOAP" OR "Technology"

= "ASPNET" OR "Technology" = "HPS"

Visual Studio, 　　　Query: "DocSet" = "Visual Studio"

OR "DocSet" = "Visual Studio SDK" OR "DocSet"

= "CrystalReports" OR "DocSet" = "Visual

Source Safe" OR "DocSet" = "VSAnalyzer"

OR "DocSet" = "PSDK" OR "DocSet"

= "NETFramework" OR "DocSet" = "NETFrameworkExtender"

OR "DocSet" = "NETEnterpriseServers" OR

("DocSet" = "kbmsdn" AND "ProductVers"

= "kbVS700")

Visual C#, 　　　　　Query: "DocSet" = "C#" OR

"DocSet" = "NETFramework" OR "DocSet"

= "NETFrameworkExtender" OR "DocSet" = "DHTML"

OR "DocSet" = "XML" OR ("DocSet"

= "kbmsdn" AND "ProductVers" = "C#")

Samples, Query: "TopicType"="kbSampleProd"

Visual FoxPro, 　　　Query: "DocSet" = "Visual FoxPro"

OR ("DocSet" = "kbmsdn" AND "ProductVers"

= "kbVFP700")

Knowledge Base, 　　Query: "DocSet" = "kbKB"

Visual J#,　　　　 　Query: "DocSet" = "VJ#"

OR "DocSet" = "NETFramework" OR "DocSet"

= "NETFrameworkExtender" OR "DocSet" = "DHTML"

OR "DocSet" = "XML" OR ("DocSet"

= "kbmsdn" AND "ProductVers" = "VJ#")

.NET Framework 精簡版, Query: "DocSet"="Smart Devices"

OR "DocSet"="NetCompactFramework"

中文(簡體)文檔,　　　 Query: ("Locale"="kbChineseSimp")

將您的幫助集合加入上面這些篩選器的搜索范圍，可以很簡單的指定文檔引擎的 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 配置文件包含進您的安裝包。)

下面是完整的步驟:

設置文檔引擎的 GenerateCollectionFiles 為 true

將編譯生成的幫助文件(*.HxS, *.HxI 等)，和生成的 INI 文件包含到安裝包中。

將 H2Reg.exe 和 H2Reg.ini (此文件可以從 H2Reg 安裝路徑中拷貝出來)包含到安裝包中。

配置安裝包，讓安裝包安裝時，將幫助文件和生成的 INI 文件復制到安裝路徑下。

安裝動作：執行 H2Reg，語法為:

H2reg -r "CmdFile="

卸載動作：執行 H2Reg，語法為:

H2reg -u "CmdFile="

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

概述

MSDN 文檔引擎用于生成如 .NET Framework SDK 類庫文檔樣式的代碼文檔，并編譯為 HTML Help 1

格式的單一文件(*.CHM)。

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

.NET Framework SDK 文檔的樣式。

配置

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

配置項

說明

AdditionalContentResourceDirectory

頁面中涉及到的資源文件(如圖片等)所在的目錄。此目錄及其子目錄中的所有文件，將以原有的目錄結構包含進

HTML Help 項目中，使用相對路徑的超鏈接不需要做大的調整。

注意: 此文件夾中第一層次的文件，和 NDoc 生成的 HTML 文件、以及通過 FilesToInclude 包含進來的文件，將處在同一層次上，請依次類推其他文件的相對

URL。

BinaryTOC

是否以二進制方式創建目錄樹文件。這將顯著提高大尺寸 CHM 文件的打開速度。

ExtensibilityStylesheet

用戶自定義的 NDoc 擴展 XSLT 轉換文件，用于轉換用戶自定義的特殊標記。請參見

NDoc 可擴展性。

FilesToInclude

指定需要包含在 HTML Help 項目中的附加文件。(1)允許使用絕對路徑或相對路徑指定，相對路徑相對于

NDoc 項目文件所在目錄。(2)可以使用通配符 * 和 ?，如 D:\preparedDocs\*.html。(3)可以有多個地址，用符號

"|" 隔開。

FooterHtml

自定義的 HTML 頁腳。您可以直接使用 HTML 代碼，其中: "%FILE_NAME%"

將被自動替換為頁面的文件名，"%TOPIC_TITLE%" 被替換為該頁面的標題文字，"%ASSEMBLY_NAME%"

和 "%ASSEMBLY_VERSION%" 分別被替換為當前頁面對應類型所屬程序集的名稱和版本信息。

HeaderHtml

自定義的 HTML 頁頭。您可以直接使用 HTML 代碼，其中: "%FILE_NAME%"

將被自動替換為頁面的文件名，"%TOPIC_TITLE%" 則被替換為該頁面的標題文字。

HtmlHelpName

一個名稱，用于命名生成的 HTML Help 項目以及將要生成的 CHM 文件。

IncludeFavorites

是否在生成的 HTML Help 文件中包含“收藏”選項卡。

LangID HTML Help

文件的 LangID 設置。中文版默認為 2052。

OutputDirectory

輸出文件目錄，生成的 .html 和 .chm 文件都將存放于此目錄。

OutputTarget

輸出目標格式: HTML Help (.chm) 或 Web 網頁或兩者都輸出。

RootPageContainsNamespaces

如果為真，RootPageFileName指定的主頁面，將在目錄樹中表示為所有命名空間結點的容器(父結點)。否則，將和其他命名空間結點并列表示。

RootPageFileName

通過此項指定 HTML Help 文件中的主頁面文件名。注：此處主頁指打開 CHM

文件時顯示的第一個頁面，請通過 RootPageTOCName 指定此主頁面在目錄樹中的顯示名稱；通過 RootPageContainsNamespaces

指定此主頁面在目錄樹中的顯示樣式；可以通過 FilesToInclude 將此文件引入到此 HTML Help 項目中來。

RootPageTOCName

HTML Help 文件中，主頁在目錄樹中的顯示名稱。若 RootPageFileName

指定了某一頁面，而此項沒有指定，則將在目錄樹中顯示“概述”作為名稱。注：此處主頁指打開 CHM 文件時顯示的第一個頁面。

SdkLinksOnWeb

如果為真，類庫中所有指向 .NET Framework 標準類庫的文檔超鏈接都將指向

MSDN 的在線版本。否則，將指向本地版本。

ShowVisualBasic

是否為類型和成員顯示 Visual Basic 語法塊。

Title

此文本將顯示在每個頁面的左上角，一般填寫類庫的名稱比較合適。

將附加的文件加入要編譯的 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)。

配置

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

配置項

說明

AdditionalContentResourceDirectory

頁面中涉及到的資源文件(如圖片等)所在的目錄。此目錄及其子目錄中的所有文件，將以原有的目錄結構包含進

HTML Help 項目中，使用相對路徑的超鏈接不需要做大的調整。

注意: 此文件夾中第一層次的文件，和 NDoc 生成的 HTML 文件、以及通過 FilesToInclude 包含進來的文件，將處在同一層次上，請依次類推其他文件的相對

URL。

BinaryTOC

是否以二進制方式創建目錄樹文件。這將顯著提高大尺寸 CHM 文件的打開速度。

ExtensibilityStylesheet

用戶自定義的 NDoc 擴展 XSLT 轉換文件，用于轉換用戶自定義的特殊標記。請參見

NDoc 可擴展性。

FilesToInclude

指定需要包含在 HTML Help 項目中的附加文件。(1)允許使用絕對路徑或相對路徑指定，相對路徑相對于

NDoc 項目文件所在目錄。(2)可以使用通配符 * 和 ?，如 D:\preparedDocs\*.html。(3)可以有多個地址，用符號

"|" 隔開。

FooterHtml

自定義的 HTML 頁腳。您可以直接使用 HTML 代碼，其中: "%FILE_NAME%"

將被自動替換為頁面的文件名，"%TOPIC_TITLE%" 被替換為該頁面的標題文字，"%ASSEMBLY_NAME%"

和 "%ASSEMBLY_VERSION%" 分別被替換為當前頁面對應類型所屬程序集的名稱和版本信息。

HeaderHtml

自定義的 HTML 頁頭。您可以直接使用 HTML 代碼，其中: "%FILE_NAME%"

將被自動替換為頁面的文件名，"%TOPIC_TITLE%" 則被替換為該頁面的標題文字。

HtmlHelpName

一個名稱，用于命名生成的 HTML Help 項目以及將要生成的 CHM 文件。

IncludeFavorites

是否在生成的 HTML Help 文件中包含“收藏”選項卡。

LangID HTML Help 文件的 LangID 設置。中文版默認為 2052。

OutputDirectory

輸出文件目錄，生成的 .html 和 .chm 文件都將存放于此目錄。

OutputTarget

輸出目標格式: HTML Help (.chm) 或 Web 網頁或兩者都輸出。

RootPageContainsNamespaces

如果為真，RootPageFileName 指定的主頁面，將在目錄樹中表示為所有命名空間結點的容器(父結點)。否則，將和其他命名空間結點并列表示。

RootPageFileName

通過此項指定 HTML Help 文件中的主頁面文件名。注：此處主頁指打開 CHM

文件時顯示的第一個頁面，請通過 RootPageTOCName 指定此主頁面在目錄樹中的顯示名稱；

RootPageContainsNamespaces

指定此主頁面在目錄樹中的顯示樣式；可以通過 FilesToInclude 將此文件引入到此

HTML Help 項目中來。

RootPageTOCName

HTML Help 文件中，主頁在目錄樹中的顯示名稱。若

RootPageFileName

指定了某一頁面，而此項沒有指定，則將在目錄樹中顯示“概述”作為名稱。注：此處主頁指打開

CHM 文件時顯示的第一個頁面。

SdkLinksOnWeb

如果為真，類庫中所有指向 .NET Framework 標準類庫的文檔超鏈接都將指向

MSDN 的在線版本。否則，將指向本地版本。

Title

此文本將顯示在每個頁面的左上角，一般填寫類庫的名稱比較合適。

將附加的文件加入要編譯的 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 可擴展性 和 實現一個新的文檔引擎。

配置

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

配置項

說明

OutputFile

輸出 XML 文件名。XML 文檔引擎輸出 NDoc 文檔生成器所使用的中間 XML

格式數據，適用于自定義文檔引擎的制作與調試。

概述

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

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

項目管理員。

配置

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

配置項

說明

Title JavaDoc

項目標題。

OutputDirectory

存放輸出 HTML 文件的文件夾。

可以為絕對路徑或者相對于 NDoc 項目文件的相對路徑。

概述

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

配置

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

配置項

說明

OutputDirectory

目標 HTML 文件的輸出目錄。

Title

HTML 頁的標題。

IncludeTypeMemberDetails

是否輸出類型成員的細節(如：是否顯示字段、屬性的“備注”等，是否單獨顯示方法的參數表格)

MethodParametersInTable

是否在同一表格中顯示方法的參數列表。

TypeIncludeRegexp

一個正則表達式，設置此項可以過濾類型的輸出，只有符合正則表達式的類型被輸出。留空白則輸出全部。

amespaceExcludeRegexp

一個正則表達式，設置此項可以過濾命名空間的輸出，符合正則表達式的命名空間被過濾。留空白則關閉過濾。

概述

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

您需要安裝一個 LaTeX 編譯器，比如免費的 MiKTeX。關于 LaTeX 的中文支持問題，請參見

CTeX: 中文 TeX 網站 中的相關內容。

配置

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

配置項

說明

OutputDirectory

文件輸出目錄。

LatexCompiler LaTeX

編譯器路徑。(如果您沒有安裝 LaTeX 編譯器，請保持空白。)

TexFileBaseName

目標 LaTeX 文件名，請不要加擴展名。

NDoc 內置的 MSDN, MSDN 2003,

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

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

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

Section 標記

Section 標記用于定義不同的代碼文檔的區域。它們都是頂級標記，Block 標記、Inline 標記都應包含在某個 Section

標記的內部。(除非自定義了擴展 XSLT 轉換，否則，在 Section 標記外部的 Block 標記或 Inline 標記都被忽略。)

標記

說明

[NDoc 擴充]

對某個成員可能引發的事件的說明。

“示例”，幫助類庫使用者理解類型/成員使用方法的示例代碼。

對某個成員可以拋出的異常的說明。

[NDoc 擴充]

指示 NDoc 文檔引擎將被標記的類型/成員排除在代碼文檔之外。與文檔引擎的“可見性”配置不符的，以

exclude 優先。

將代碼文件外部的某 XML 文件中的一部分包含進代碼文件來。

[NDoc 擴充]

為“重載列表”頁面準備摘要、備注、示例等文檔內容。只需在重載成員的第一個成員前面書寫此區域即可。

標記有兩種形式:

簡單的形式，直接在 overload 中寫文本，這些文本被處理為“重載列表”頁面的摘要。沒有備注、示例等區域。

復雜的形式，在 overload 內部，包含 summary, remarks, example 等標記分別表示“重載列表”頁面的摘要、備注、示例等。

示例:

///This method has two

overloads.

///This overload just says hello.

public void SayHello() { ... }

///This one says hello to someone.

public void SayHello(string toSomeone) { ... }

成員的參數說明。

訪問某成員所必需的 .NET Framework 安全性 CodeAccessPermission。

[NDoc 擴充]

將某類型/成員標記為“預發布”。內部的文本被當作警告文本用紅色顯示，可以包含 表示多行文本。如果缺少內部文本，則顯示默認的警告文本:

“[此文檔為預發布版本，在未來版本中有可能改變。]”。

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

配置項。

“備注”，對 的進一步注解。

“返回值”。

向頁面的“請參見”區域添加一個鏈接。

請不要將此標記包含在

內部，它是一個頂級標記。

兩種可選的語法:

MSDN(CHS)

DataSet

“摘要”，對類型/成員的摘要說明。

[NDoc 擴充]

“線程安全”，說明類型在多線程環境中是否安全。

NDoc

提供 static 和 instance 兩個布爾的屬性，可以自動生成像 .NET Framework SDK 類庫文檔中那樣的標準文本。

threadsafety 標記內部可以包含額外的文本，會被顯示到標準文本的下方，說明額外的信息。例如:

/// The summary description

for SafeClass.

///

/// More information about using this class across

thread

///

public class SafeClass() { ... }

“屬性值”。

Block 標記

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

標記

說明

多行的代碼塊。

一個列表或表格。

[NDoc 擴充]

“注意”塊。

例如:

///

/// This is a note in the summary.

///

public class SomeClass() { ... }

將生成:

注意 This is a note in the summary.

表示一個段落。

Inline 標記

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

標記

說明

將內部文本格式化為代碼樣式，用于表示行文中提到的短小代碼片段。

加入指向方法參數的鏈接。

加入指向某個類型/成員或網絡 URL 的鏈接。

兩種可選的語法:

MSDN(CHS)

DataSet

其中 xxx 可以是 null, sealed, static, abstract 或 virtual。

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

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

text

其中:

text

要標記為代碼樣式的文本。

應用于

可用于其他標記內部。

備注

如果需要標記多行的代碼塊，請使用 標記。

示例

[C#]

public class MyClass

{

///

/// MyMethod is a method in the MyClass

class.

///

public static void MyMethod(int Int1)

{

}

}

標記指示將其內部的文本表示為代碼樣式，Block 標記，用于表示多行的代碼塊。

content

其中:

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

///

/// Loads the XML.

///

/// The XML should have the following format.

///

///

///

///

///

///

public void LoadXml(string xml)

{

//do something here...

}

標記用于說明被標記的方法可能引發的事件。Section

標記。

description

其中:

cref = "member"

表示可能引發的事件。書寫時，如果可能引發的事件是同一類型的事件，member 可以直接寫事件名稱(注意大小寫)；如果是其他類型的，建議您寫該事件的完全限定名稱。C#

編譯器將檢查該事件是否存在。在輸出的 XML 文檔文件中，C# 編譯器會自動轉換簡寫的 member 為完全限定名稱。

description

附加的說明，比如在什么情況下引發該事件。

應用于

方法成員。

備注

示例

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

description

其中:

description

示例及其說明。

應用于

所有的類型及成員。

備注

此標記經常和 標記聯用。

示例

[C#]

public class MyClass

{

///

/// The GetZero method.

///

/// This sample shows how to call the GetZero method.

///

/// class MyClass

/// {

/// public static int Main()

/// {

/// return GetZero();

/// }

/// }

///

///

public static int GetZero()

{

return 0;

}

}

標記用于說明一個成員可能拋出的異常。

description

其中:

cref = "member"

表示可能拋出的異常類型。書寫時，如果可能拋出的異常是同一命名空間下的異常類型，member 可以直接寫異常名稱(注意大小寫)；如果是其他命名空間的，建議您寫該異常類型的完全限定名稱。C#

編譯器將檢查該異常是否存在。在輸出的 XML 文檔文件中，C# 編譯器會自動轉換簡寫的 member 為完全限定名稱。

description

說明信息，比如在什么情況下拋出該異常。

應用于

屬性, 方法, 事件, 運算符, 類型轉換

備注

示例

[C#]

using System;

/// comment for class

public class EClass : Exception

{

// class definition ...

}

class TestClass

{

/// Thrown when... .

public static void Main()

{

...

throw new EClass();

...

}

}

標記指示 NDoc 文檔引擎將被標記的類型/成員排除在代碼文檔之外。

應用于

所有的類型及成員。

備注

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

示例

請參見

標記指示將代碼文件(*.cs)外部的某

XML 文件中的一部分、作為 XML 文檔注釋、包含進代碼文件來。

/>

其中:

filename

包含 XML 文檔注釋的文件名。該文件名可包含路徑。將 filename 括在單引號中 (' ')。

tagpath

filename 中指向標記名的標記路徑(使用 XPath 語法)。將此路徑括在單引號中 (' ')。

name

注釋前邊的標記中的名稱說明符；名稱具有一個 id。

id

位于注釋之前的標記的 ID。將此 ID 括在雙引號中 (" ")。

應用于

所有的類型及成員。

備注

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

標記使用 XML XPath 語法。有關自定義

使用的方法，請參見 XPath 文檔。

示例

以下是一個多文件示例。第一個文件使用 ，如下所列：

[C#]

///

/>

class Test

{

public static void Main()

{

}

}

///

/>

class Test2

{

public void Test()

{

}

}

第二個文件 xml_include_tag.doc 包含下列文檔注釋：

The summary for this type.

The summary for this other type.

編譯器輸出的 XML 文檔

t2

The summary for this type.

The summary for this other type.

標記表示一個列表(數字列表或符號列表)，或一個表格，或一個定義表。Block

標記。

| "table" | "definition">

term

description

term

description

其中:

term

要定義的項，該項將在 description 中說明/定義。

description

對 term 的說明/定義。

備注

可以表示為四種樣式：bullet 為符號列表，即對應于 HTML 中的 UL 列表；number 為數字列表，即對應于

HTML 中的 OL 列表；table 為表格，將以表格形式表示；definition 為定義列表，顯示效果就像本頁上方“其中”二字下面對

term 和 description 的定義那樣。

對 table 和 definition 有效。對 table，需要為

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

塊表示列表中的一項。item 包含子元素 term 和 description。對

bullet 和 number 列表，term 無效也不需要寫。對 table 表，可以沒有 term，只寫 description。對

definition 表，term 和 description 都應該有。

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

示例

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

| "implementnotes">

description

其中:

description

注意事項。

應用于

可用于其他標記內部。

備注

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

示例

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

簡單語法

summary_description

復合語法

summary_description

[remarks_description]

[examples_description]

應用于

屬性, 方法, 事件, 運算符。

備注

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

此標記有兩種形式:

簡單的形式，直接在 overload 中寫文本，這些文本被處理為“重載列表”頁面的摘要。沒有備注、示例等區域。

復雜的形式，在 overload 內部，包含 summary, remarks, example 等標記分別表示“重載列表”頁面的摘要、備注、示例等。

示例

///This

method has two overloads.

///This overload just says hello.

public void SayHello() { ... }

///This one says hello to someone.

public void SayHello(string toSomeone) { ... }

標記表示一個段落。

content

where:

lang="language" [NDoc 擴充]

表示語言選擇器，指示此段落僅對某種編程語言有效。(可選)

content

段落文本。

應用于

可用于其他標記內部。

備注

此標記經常用于 , , 及 等標記內部。

使用 lang 屬性表示語言選擇器，標準的語言有: Visual Basic, C#, C++

及 JScript。若代碼塊適用于多種語言，則用逗號隔開，比如“Visual Basic, C#, C++”。

示例

請參見 的示例。

The tag describes

one of the parameters for the method.

description

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

{

/// Used to indicate status.

public static void MyMethod(int Int1)

{

}

/// text for Main

public static void Main ()

{

}

}

See Also

標記引用一個參數，將以代碼樣式表示該參數名稱。

其中:

name

參數的名稱。

應用于

可用于其他標記內部。

備注

示例

[C#]

/// text for class MyClass

public class MyClass

{

/// MyMethod is a method in the MyClass class.

/// The parameter takes

a number.

///

public static void MyMethod(int Int1)

{

}

/// text for Main

public static void Main ()

{

}

}

標記說明訪問某成員所必需的 .NET Framework

安全性 CodeAccessPermission。

description

其中:

cref = "member"

表示需要的 CodeAccessPermission 類型。書寫時，如果 CodeAccessPermission 是同一命名空間下的類型，member

可以直接寫其名稱(注意大小寫)；如果是其他命名空間的，建議您寫該 CodeAccessPermission 的完全限定名稱。C#

編譯器將檢查該 CodeAccessPermission 是否存在。在輸出的 XML 文檔文件中，C# 編譯器會自動轉換簡寫的

member 為完全限定名稱。

description

其他說明。

應用于

所有成員。

備注

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

示例

[C#]

using System;

class TestClass

{

/// Everyone

can access this method.

public static void Test()

{

}

public static void Main()

{

}

}

標記將類型/成員標記為“預發布”。

[description]

其中:

description

對“預發布”的說明文本。(可選)

應用于

所有的類型及成員。

備注

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

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

示例

[C#]

// The class summary will get the default message

///

public class MyClass

{

///

/// This method is just for testing right now. It might

be removed in the near future

///

public void Dump ()

{

}

}

標記表示對類型或成員的“備注”。

description

其中:

description

對類型/成員的“備注”。

應用于

所有的類型及成員。

備注

標記用于對 摘要信息的補充。.

示例

[C#]

///

/// You may have some primary information about this class.

///

///

/// You may have some additional information about this class.

///

public class MyClass

{

/// text for Main

public static void Main ()

{

}

}

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

description

其中:

description

對方法的返回值的說明。

應用于

方法。

備注

示例

[C#]

/// text for class MyClass

public class MyClass

{

/// Returns zero.

public static int GetZero()

{

return 0;

}

/// text for Main

public static void Main ()

{

}

}

標記用于在行文中添加一個超鏈接。

[label]

或

[label]

或

其中:

label

超鏈接的顯示文本。

cref = "member"

表示要鏈接到的類型(成員)。書寫時，如果要鏈接到的類型(成員)是同一命名空間(類型)中的類型(成員)，member 可以直接寫它的名稱(注意大小寫)；如果是其他命名空間(類型)的，建議您寫該類型(成員)的完全限定名稱。C#

編譯器將檢查該類型(成員)是否存在。在輸出的 XML 文檔文件中，C# 編譯器會自動轉換簡寫的 member 為完全限定名稱。

href = "URL" [NDoc 擴充]

一個網絡 URL 地址。

langword [NDoc 擴充]

將會被當作 .NET 關鍵字粗體顯示。如果 langword 是下面備注中的表格里的某個關鍵字，還將會被替換為相應的說明文本。

應用于

可用于其他標記內部。

備注

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

注意: 在 NDoc 1.3 中，對于 MSDN 和 VS.NET 文檔引擎，如果一個區域出現了多個指向同一個類型/成員的文檔的

，則只轉換第一個為超鏈接，其余的不表示為超鏈接、只顯示為粗體。這將使頁面不至于太雜亂。

可識別的 langword

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

langword

顯示

null

空引用(Visual Basic 中為 Nothing)

sealed

密封的(Visual Basic 中為 NotInheritable)

static

靜態(Visual Basic 中為 Shared)

abstract

抽象(Visual Basic 中為 MustInherit)

virtual

虛擬(Visual Basic 中為 CanOverride)

示例

請參見 中的示例。

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

[label]

或

[label]

其中:

label

超鏈接的顯示文本。

cref = "member"

表示要鏈接到的類型(成員)。書寫時，如果要鏈接到的類型(成員)是同一命名空間(類型)中的類型(成員)，member 可以直接寫它的名稱(注意大小寫)；如果是其他命名空間(類型)的，建議您寫該類型(成員)的完全限定名稱。C#

編譯器將檢查該類型(成員)是否存在。在輸出的 XML 文檔文件中，C# 編譯器會自動轉換簡寫的 member 為完全限定名稱。

href = "URL" [NDoc 擴充]

一個網絡 URL 地址。

應用于

所有的類型及成員。

備注

使用 標記在行文中添加超鏈接。

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

示例

請參見 中的示例。

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

description

其中:

description

對類型或成員的摘要說明。

應用于

所有的類型及成員。

備注

此標記是所有類型及成員最基本的說明，一般的，應為每個公共的、可見的類型/成員書寫 summary 文檔。在 Visual Studio

.NET IDE 的智能感知功能及對象查看器，還有其他大多數開發工具，都會顯示 summary 信息。

標記用于更詳細的說明。

示例

[C#]

/// text for class MyClass

public class MyClass

{

/// MyMethod is a method in the MyClass class.

/// Here's how you could make a second paragraph in

a description.

for information about output statements.

///

///

public static void MyMethod(int Int1)

{

}

/// text for Main

public static void Main ()

{

}

}

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

其中:

static="true|false"

指示類型的靜態成員在多線程環境中是否是安全的。

instance="true|false"

指示類型的實例成員在多線程環境中是否是安全的。

應用于

類, 結構。

備注

示例

[C#]

///

public class MyClass

{

/// not safe across threads

public void InstanceMethod()

{

}

/// safe across threads

public static void StaticMethod()

{

}

}

標記用于說明屬性的值。

property-description

其中:

property-description

對屬性值的說明。

應用于

屬性。

備注

按照約定，總是應該為屬性書寫 標記。

示例

[C#]

/// text for class MyClass

public class MyClass

{

/// MyProperty is a property in the MyClass class.

/// A string containing the text "MyProperty String".

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

/// This is a custom tag

///

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

///

/// This is a test of an inline tag

public class ABunchOfCustomTags

{

}

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

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

xmlns:MSHelp="http://msdn.microsoft.com/mshelp">

mode="xml-data-island" priority="1">

Value="Windows"/>

mode="header-section">

.green

{

color:green;

}

mode="slashdoc">

null reference (Nothing

in Visual Basic)

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

如上面示例中看到的那樣，使用 stylesheet 中的 templates“匹配(match)”您的自定義標記。match

是 XPath 查詢的一種，指示 template 將應用于哪些標記。簡單的用法是直接匹配您的自定義標記，當然還可以有更高級的用法，對

XSLT 高手們應當是小菜一碟。

注意: 如果您定義的自定義標記中還包含其他標記，您應當加入下面的命令，讓它轉換這些內含的標記(比如

等)：

上例中還展示了向 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 屬性的值，指示該標記將顯示在代碼文檔中的區域。

Section 名稱

說明

header-section

HTML 的 HEAD 區域。可以使用此區域添加附加的樣式定義等。

preliminary-section

“預發布”警告區域。僅當注釋文檔中使用 標記顯式標出，或通過文檔引擎的

Preliminary 配置為 true 時，才會顯示該區域。

summary-section

標記對應的區域。tag.

thread-safety-section

“線程安全”區域。

syntax-section

“語法”區域。

value-section

標記對應的“屬性值”區域。

parameter-section

標記對應的“參數”區域。

returnvalue-section

標記對應的“返回值”區域。

implements-section

“接口實現”區域。

remarks-section

標記對應的“備注”區域。

after-remarks-section

“備注”區域后的區域。

注意: 不管“備注”區域是否存在，此區域總是存在的。

obsolete-section

“已過時”區域。

events-section

標記對應的“事件”區域。

exceptions-section

標記對應的“異常”區域。

example-section

標記對應的“示例”區域。

member-requirements-section

(某一個成員的)“要求”區域。

type-requirements-section

(類型的)“要求”區域。

seealso-section

“請參見”區域。

enumeration-members-section

“枚舉成員”區域。

footer-row

頁腳區域。

title-row

頁眉區域。

overloads-remarks-section

重載頁面的“備注”區域。

overloads-example-section

重載頁面的“示例”區域。

overloads-summary-section

重載頁面的“摘要”區域。

xml-data-island

HTML部嵌入的 XML 數據區域，可以附加自定義的元素或內容。 僅對 VS.NET

2003 文檔引擎有效。

實現一個新的文檔引擎

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

一個從 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..dll

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

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

(中文版注：如果您寫有關于 NDoc 中文介紹的不錯文章，請告訴譯者，我正在考慮在這里加入一個中文 NDoc 文章的列表。)

總結

以上是生活随笔為你收集整理的access和tagware_NDoc 用户指南的全部內容，希望文章能夠幫你解決所遇到的問題。

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