NDoc –NET 代碼文檔生成器快速度上手

                         感謝：破寶 http://blog.joycode.com/percyboy/

       在線資源：NDoc 1.3 中文版用戶指南  

       下載：NDoc中文版安裝包下載 NDoc源碼下載

NDoc 是一個很好用的.NET小工具，它可以將 C#.NET 編譯生成的程序集和對應的 /doc XML 文檔，自動轉換成如 .NET Framework SDK 類庫文檔或者 MSDN Library 在線 .NET 類庫文檔形式的代碼文檔，讓您快速擁有專業級的類庫API 文檔。(VB.NET 通過第三方插件如 VBCommenter 的支持，也可以生成 XML 文檔。) 這裏不多說了，現在說說怎麼快速使用NDoc生成文檔.

首先配置我們自己的C#項目，讓我們的程序集生成XML文檔

注意：XML文檔文件名和程序集同名，省去不必要的麻煩；在 NDoc 中，當您加入某程序集時，NDoc 會自動查找這樣的“同名” XML 文件。如果找到，就會嘗試自動將它當作該程序集的 XML 文檔。這樣會簡化您的操作。

第二步：完善自己的程序的相關注釋

比如在一個函數前面輸入“///”.NET會自動創建一個 summary XML 文檔塊:

/// <summary>

///

/// </summary>

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

/// <param name="s2"></param>

作用也一目瞭然，生成文檔的時候這是很有用的。你的註釋越是詳細，你生成的文檔就會越專業。

這裏不得不對比國內和國外的情況了，國內我們的程序員往往花N多時間完成了一個不錯的軟件或者類庫什麼的，往往什麼文檔也沒有，別人想學習，想用你的東西，往往被一對煩亂的代碼堆砌，嚇跑了。那麼這個軟件或者類庫有何意義呢，能給別人帶來幫助嗎？國外的做法和國內的相差就太大了，他們往往花一半的時間完善他們的註釋文檔工作，往往10行的小代碼段，會有20行的註釋，這是很多人無法想象的，但是何爲目光短淺，相信聰明人自然明瞭。

繼續說我們的註釋，NDoc還支持狠毒其他的標記，需要我們自己輸入的，生成文檔的時候會看到相應的效果，具體怎麼用，往下看。

NDoc支持許多有用的標記，下面有張列表

標記	說明
<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>	成員的參數說明。
<permission>	訪問某成員所必需的 .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工具了

如果您使用 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 文檔引擎

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

這裏還有要說的就是這些文檔引擎，需要安裝相應的支持工具

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。

生成代碼文檔

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

 

NDoc 生成進度

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

最後，希望大家用好這個小工具，讓我們的程序代碼更有價值。