• 歡迎使用 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 文檔標記
新標記

標記
說明

<exclude/>
Directs NDoc to exclude the tagged type or member from the documentation.
The tag overrides all visibility options.

<preliminary>
Marks the documentation of a type or member as preliminary.
This tag can include text and block tags like <para> 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.

<devdoc>

增強的標記

標記
說明

<code>

• "lang" attribute
• No more <include> to prevent indent
• "Escaped" attribute

<see>
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 會用新的配置項改寫。

改進的超鏈接邏輯
<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 的已知問題和限制

事項
說明

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

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

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

比如如下的代碼:

public class MyClass() {
public MyClass( string s ) { }
}

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

public class MyClass() {
/// <summary>
///
/// </summary>
/// <param name="s"></param>
public MyClass( string s ) { }
}

這種操作對于所有可以書寫 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 標記都被忽略。）

標記
說明

<event> [NDoc 擴充]
對某個成員可能引發的事件的說明。

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

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

<exclude/>

[NDoc 擴充]

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

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

<overloads>

[NDoc 擴充]

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

<overloads> 標記有兩種形式:

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

///<overloads>This method has two overloads.</overloads>
///<summary>This overload just says hello.</summary>
public void SayHello() { ... }
///<summary>This one says hello to someone.</summary>
public void SayHello(string toSomeone) { ... }

<param>
成員的參數說明。

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

<preliminary>

[NDoc 擴充]

將某類型/成員標記為“預發布”。內部的文本被當作警告文本用紅色顯示，可以包含 <para> 表示多行文本。如果缺少內部文本，則顯示默認的警告文本: “[此文檔為預發布版本，在未來版本中有可能改變。]”。

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

<remarks>
“備注”，對 <summary> 的進一步注解。

<returns>
“返回值”。

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

請不要將此標記包含在 <remarks> 內部，它是一個頂級標記。

兩種可選的語法:

• <seealso href="http://www.microsoft.com/china/msdn/">MSDN(CHS)</seealso>
• <seealso cref="System.Data.DataSet">DataSet</seealso>

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

<threadsafety>

[NDoc 擴充]

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

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

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

/// <summary>The summary description for SafeClass.</summary>
/// <threadsafety static="true" instance="true">
/// <para>More information about using this class across thread</para>
/// </threadsafety>
public class SafeClass() { ... }

<value>
“屬性值”。

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

標記
說明

<code>
多行的代碼塊。

<list>
一個列表或表格。

<note>

[NDoc 擴充]

“注意”塊。

例如:

/// <summary>
/// <note>This is a note in the summary.</note>
/// </summary>
public class SomeClass() { ... }
將生成:

注意 This is a note in the summary.

<para>
表示一個段落。

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

標記
說明

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

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

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

兩種可選的語法:

• <see href="http://www.microsoft.com/china/msdn/">MSDN(CHS)</see>
• <see cref="System.Data.DataSet">DataSet</see>
• <see langword="xxx"/>
  其中 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 中，我們推薦您使用 <exclude/> 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，短線和等號周圍不要有空格。下面語法敘述中，中括號的部分是可選的。路徑中如果包含有空格，則需要用引號(")括起來。

總結

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

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