生成類庫chm幫助文檔
目 錄
第一章
生成文檔說明
一.1 生成幫助文檔的作用
項目開發與各部門配合時,給他們提供一個外部服務,既然是提供給別人（研發、測試等）使用的,當然需要告訴別人怎麼來用你的服務,這也就是我們常說的技術文檔。各組之間傳遞技術文檔的方式有很多種。這裏我知道的大概有以下幾種：
第一：口頭傳遞技術文檔，也就是沒有實質的文檔資料，口頭說明一下即可，這種情況侷限於溝通起來非常方便的開發團隊中，例如就坐在一個辦公間等等。
第二：以文本形式，把如何使用的技術點記錄下來，這個方法有什麼用，那個屬性是做什麼的等等，這種方式無疑是表述最清楚的，單獨的文檔中你甚至可以用圖的方式教導使用者，但缺點就是維護起來相當麻煩，而且費時。如果哪天服務的實現有了比較大的改變，那更新這個文檔就非常麻煩了。
第三：利用工具，配合.net的註釋來自動生成幫忙文件，這裏就是本文所提到的Sandcastle Help File Builder了，後面簡稱爲SHFB。它是Sandcastle的一個可視化工具，用戶不用記住大量命令來完成文檔的編譯。它最終可以生成例如chm文件，內容風格可選MSDN，讓使用都可以感到非常親切。
一.2 Sandcastle 概述
爲了滿足這部分文檔編寫的需要，Microsoft 推出了一種用於快速生成 .NET 類庫文檔的工具，代號爲 Sandcastle，該工具用來通過代碼中的 XML 文檔註釋快速生成類似 MSDN 樣式的幫助文檔。它的文檔輸出格式支持 Help 1.x (*.chm)，Help 2.0 (HxS) 和網站 (ASP.NET 和 HTML)，您在編寫文檔上僅僅需要做的工作，就是努力的寫好所有 XML 文檔註釋，並最終利用 Sandcastle 進行批量生成。
Sandcastle 被 Microsoft 內部用來直接生成 .NET Framework 核心類庫參考文檔，它是 MSDN 和 .NET Framework SDK 的一部分。
目前，Sandcastle 沒有圖形界面，但它提供了強大的功能，包括支持 prototype 樣式、Visual Studio 2005 樣式和 Visual Studio 2008 新的文檔設計樣式；它能對代碼示例進行語法高亮，自動生成多種語言的過濾、語法、生成索引、內容目錄、搜索；除此之外，它提供的命令行工具和批處理文件能夠幫助我們生成自定義的幫助文檔的本地化版本。
Sandcastle 提供的主要命令行工具有兩個：BuildAssembler.exe 和 XslTransform.exe。BuildAssembler 用來對幫助文檔源 (*.dll, *.exe, *.xml) 進行反射，找到所有的可用於生成文檔的程序集、命名空間和類型，以及它們附加的 XML 文檔註釋，生成待轉換的 XML 文件；XslTransform 用來對 BuildAssembler 生成的 XML 文件轉換成特定的輸出格式，如 Visual Studio 2005 樣式的 chm 文件
注：Sandcastle 支持將多個程序集的XML文檔註釋生成一個chm文件的功能，可以將多個程序集和對應XML文檔註釋分別放在兩個文件夾下，然後用AddFolder功能 一次性將文件夾下的文件添加到項目中，這樣就可以將多個程序集的XML註釋合併生成一個CHM文檔了。
一.3 生成文檔有以下特點
類似於MSDN佈局的界面。
自動生成索引項、內容項目表、主題塊和頁面佈局，提高一致性和熟悉程度。
自動生成語法宣稱部分。
自動生成繼承表。
代碼彩色化。
提供多種風格和語言選擇，終端用戶可從中選擇自己最喜歡的形式。
輸出結果以HTML和CSS形式顯示，微軟承諾將來提供更多選擇。
一.4 利用圖形化工具 Sandcastle Help File Builder
使用這個工具，您可以用圖形化的界面批量生成多個程序集的文檔，還能生成基於 ASP.NET 和 HTML 的網站。它只需要您簡單的作出幾個設置，就能非常方便的幫助您生成專業的，帶有高級語法過濾、語法高亮、搜索和導航功能全功能站點。
總結：Sandcastle Help File Builder能夠非常好的和VS合作，製作出MSDN風格的幫忙文檔，即有效的對項目保存了技術文檔又降低了溝通成本。
第二章 Sandcastle Help File Builder說明
二.1 SHFB的軟件環境
下載地址：
下載後解壓縮到目錄：
二.2 SHFB安裝過程
二.3 安裝步驟
按步驟進行安裝
二.4 配置項目中生成xml文檔
二.5 創建SHFB文檔項目
“File”菜單——“New Project”
右擊項面前目今的”Documentation Sources”——“Add Documentation Source…”，添加要生成文檔的.dll和.xml文件。
設置項目標屬性，如HelpTitle，HtmlHelpName等。
生成項目，“Documentation”菜單——“Buid Project”
a.打開軟件後首先新建解決方案，注意不要建在桌面等位置，否則生成時會報錯。
b.解決方案建成後，在Project Explorer 中右擊 Documentation Sources 上右擊添加需要生成幫助文檔的dll文件。圖中①處爲我添加的需要生成幫助文檔的dll文件
c.底下Content Layout1.content爲生成的幫助文檔的樣式，完全可以不要。
d.選擇要生成幫助文檔的格式，如圖中②處，我要生成html格式的幫助文檔，也可以選擇chm文檔
第三章 註釋文檔規範
三.1 註釋的必要性
.Net允許開發人員在源代碼中插入XML註釋，這在多人協作開發的時候顯得特別有用。 C#解析器可以把代碼文件中的這些XML標記提取出來，並作進一步的處理爲外部文檔。 這篇文章將展示如何使用這些XML註釋。 在項目開發中，很多人並不樂意寫繁雜的文檔。但是，開發組長希望代碼註釋儘可能詳細；項目規劃人員希望代碼設計文檔儘可能詳盡；測試、檢查人員希望功能說明書儘可能詳細等等。如果這些文檔都被要求寫的話，保持它們同步比進行一個戰役還痛苦。
爲何不把這些信息保存在一個地方呢？？最明顯想到的地方就是代碼的註釋中；但是你很難通覽程序，並且有些需要這些文檔的人並不懂編碼。最好的辦法是通過使用XML註釋來解決這些問題。代碼註釋、用戶手冊、開發人員手冊、測試計劃等很多文檔可以很方便的從XML註釋中獲得。本文講解.Net中經常使用的XML註釋.主要使用C#語言.Net平臺支持的其他語言使用的XML註釋格式基本相同.並且在本系列文章的下一講中講解如何使用工具將XML註釋內容轉化爲幫助文檔.
三.2 代碼註釋規範
代碼註釋規範需要使用以三個斜槓 (///) 開始註釋，這些註釋後面必須緊跟它們所註釋的用戶定義類型（如類、委託或接口）或者成員（如字段、事件、屬性或方法）.對註釋解說需要使用有效的xml標記。
/// <summary>
/// 用戶登錄
/// </summary>
/// <param name="loginName">登陸用戶</param>
/// <param name="loginPassword">登陸密碼</param>
/// <returns>用戶對象</returns>
[OperationContract]
User GetUserId(string loginName, string loginPassword);
這裏嵌入的summary,param,returns標記僅僅是Visual Studio能夠識別的一部分標記，然而在智能感知IntelliSense中，並沒有把c#規範中所有的標記列出來，遺失的部分只能用手工插入。 這些手工標記是非常有用的，如果恰當地設置他們，對導出成外部說明文件將非常有幫助。
三.3 常見註釋標籤列表
註釋的使用很簡單,但是我們使用到的註釋很少.這是因爲大部分項目中註釋的作用僅僅是給程序員自己看.如果想要生成類似MSDN這樣的文檔,我們需要了解更多的註釋標籤.下面是我整理的常用的註釋標籤:
標籤名稱 | 說明 | 語法 | 參數 |
<summary> | <summary> 標記應當用於描述類型或類型成員。使用<remarks> 添加針對某個類型說明的補充信息。 <summary> 標記的文本是唯一有關 IntelliSense 中的類型的信息源，它也顯示在 對象瀏覽器 中。 | <summary> Description </summary> | description:對象的摘要。 |
<param> | <param> 標記應當用於方法聲明的註釋中，以描述方法的一個參數。 有關 <param> 標記的文本將顯示在 IntelliSense、對象瀏覽器和代碼註釋 Web 報表中。 | <param name='name'> description </param> | name:方法參數名。將此名稱用雙引號括起來 (" ")。 description:參數說明。 |
<returns> | <returns> 標記應當用於方法聲明的註釋，以描述返回值。 | <returns> Description </returns> | description:返回值的說明。 |
<remarks> | 使用 <remarks> 標記添加有關類型的信息，以此補充用<summary> 指定的信息。此信息顯示在對象瀏覽器中。 | <remarks> Description </remarks> | description:成員的說明。 |
<exception> | <exception> 標記使您可以指定哪些異常可被引發。此標記可用在方法、屬性、事件和索引器的定義中。 | <exception cref="member"> Description </exception> | cref: 對可從當前編譯環境中獲取的異常的引用。編譯器檢查到給定異常存在後，將member 轉換爲輸出XML 中的規範化元素名。必須將 member括在雙引號 (" ")中。 有關如何創建對泛型類型的 cref 引用的更多信息，請參見<see> description:異常的說明。 |
<value> | <value> 標記使您得以描述屬性所代表的值。請注意，當在Visual Studio .NET 開發環境中通過代碼嚮導添加屬性時，它將會爲新屬性添加<summary> 標記。然後，應該手動添加 <value> 標記以描述該屬性所表示的值。 | <value> property-description </value> | property-description:屬性的說明 |
<example> | 使用 <example> 標記可以指定使用方法或其他庫成員的示例。這通常涉及使用 <code>標記。 | <example> Description </example> | description: 代碼示例的說明。 |
<c> | <c> 標記爲您提供了一種將說明中的文本標記爲代碼的方法。使用 <code> 將多行指示爲代碼。 | <c> Text </c> | text :希望將其指示爲代碼的文本。 |
<code> | 使用 <code> 標記將多行指示爲代碼。使用<c>指示應將說明中的文本標記爲代碼。 | <code> Content </code> | content:希望將其標記爲代碼的文本。 |
<see> <seealso> | <see> 標記使您得以從文本內指定鏈接。使用 <seealso> 指示文本應該放在“另請參見”節中。 | <see cref="member"/> | cref: 對可以通過當前編譯環境進行調用的成員或字段的引用。編譯器檢查給定的代碼元素是否存在，並將member 傳遞給輸出XML 中的元素名稱。應將 member 放在雙引號 (" ") 中。 |
<para> | <para> 標記用於諸如<summary>，<remarks> 或<returns> 等標記內，使您得以將結構添加到文本中。 | <para>content</para> | content:段落文本。 |
<code>* | 提供了一種插入代碼的方法。 | <code src="src"language="lan"encoding="c"/> | src:代碼文件的位置 language:代碼的計算機語言 encoding:文件的編碼 |
<img>* | 用以在文檔中插入圖片 | <img src="src"/> | src:圖片的位置，相對於註釋所在的XML文件 |
<file>* | 用以在文檔中插入文件，在頁面中表現爲下載鏈接 | <file src="src"/> | src:文件的位置，相對於註釋所在的XML文件 |
<localize>* | 提供一種註釋本地化的方法，名稱與當前線程語言不同的子節點將被忽略 | <localize> <zh-CHS>中文</zh-CHS> <en>English</en> ... </localize> |
三.4 <Summary>
三.5 類註釋
三.6 方法註釋
需要注意的幾點:
1) 最開始seealso標籤添加在了remarks標籤中,所以在See Also區域沒有添加上方法的連接. 解決方法是把seealso標籤放在summary標籤中.
2) 異常類的cref屬性需要設置成編譯器可以識別的類, 這樣纔可以在幫助文檔中點擊.比如上面的System.ApplicationException異常點擊後進入微軟的在線MSDN查詢.如果是自己定義的異常, 需要此異常類也在你的幫助文件中.一般提供註釋XML和依賴DLL即可.
三.7 屬性註釋
屬性的註釋也很簡單.和類不同的地方在於屬性要使用<value>標籤而不是<remarks>進行描述
第四章 參考資料
1、 使用SandCastle創建.Net幫助文檔
http://www.cnblogs.com/DotNetNuke/archive/2009/04/23/1441899.html
2、 Sandcastle Help File Builder源碼
http://shfb.codeplex.com/releases/view/121365
3、 Sandcastle源碼
http://sandcastle.codeplex.com/SourceControl/latest
http://sandcastle.codeplex.com/releases/view/47665
4、 使用.NET中的XML註釋
http://www.cnblogs.com/zhangziqiu/archive/2009/01/23/1380416.html
文章中的部份圖片來源網絡的圖片，版權歸相關圖片的所有者。
如果圖片有對您造成影響，可聯繫我處理。