溫馨提示×
您好，登錄后才能下訂單哦！
點擊 登錄注冊 即表示同意《億速云用戶服務條款》
您好，登錄后才能下訂單哦！
生成類庫chm幫助文檔
目 錄
第一章配置說明3
1.1本地服務器信息3
項目開發與各部門配合時,給他們提供一個外部服務,既然是提供給別人（研發、測試等）使用的,當然需要告訴別人怎么來用你的服務,這也就是我們常說的技術文檔。各組之間傳遞技術文檔的方式有很多種。這里我知道的大概有以下幾種：
第一：口頭傳遞技術文檔，也就是沒有實質的文檔資料，口頭說明一下即可，這種情況局限于溝通起來非常方便的開發團隊中，例如就坐在一個辦公間等等。
第二：以文本形式，把如何使用的技術點記錄下來，這個方法有什么用，那個屬性是做什么的等等，這種方式無疑是表述最清楚的，單獨的文檔中你甚至可以用圖的方式教導使用者，但缺點就是維護起來相當麻煩，而且費時。如果哪天服務的實現有了比較大的改變，那更新這個文檔就非常麻煩了。
第三：利用工具，配合.net的注釋來自動生成幫忙文件，這里就是本文所提到的Sandcastle Help File Builder了，后面簡稱為SHFB。它是Sandcastle的一個可視化工具，用戶不用記住大量命令來完成文檔的編譯。它最終可以生成例如chm文件，內容風格可選MSDN，讓使用都可以感到非常親切。
為了滿足這部分文檔編寫的需要，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文檔了。
類似于MSDN布局的界面。
自動生成索引項、內容項目表、主題塊和頁面布局，提高一致性和熟悉程度。
自動生成語法宣稱部分。
自動生成繼承表。
代碼彩色化。
提供多種風格和語言選擇，終端用戶可從中選擇自己最喜歡的形式。
輸出結果以HTML和CSS形式顯示，微軟承諾將來提供更多選擇。
使用這個工具，您可以用圖形化的界面批量生成多個程序集的文檔，還能生成基于 ASP.NET 和 HTML 的網站。它只需要您簡單的作出幾個設置，就能非常方便的幫助您生成專業的，帶有高級語法過濾、語法高亮、搜索和導航功能全功能站點。
總結：Sandcastle Help File Builder能夠非常好的和VS合作，制作出MSDN風格的幫忙文檔，即有效的對項目保存了技術文檔又降低了溝通成本。
下載地址：
下載后解壓縮到目錄：
按步驟進行安裝
“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文檔
.Net允許開發人員在源代碼中插入XML注釋，這在多人協作開發的時候顯得特別有用。 C#解析器可以把代碼文件中的這些XML標記提取出來，并作進一步的處理為外部文檔。 這篇文章將展示如何使用這些XML注釋。 在項目開發中，很多人并不樂意寫繁雜的文檔。但是，開發組長希望代碼注釋盡可能詳細；項目規劃人員希望代碼設計文檔盡可能詳盡；測試、檢查人員希望功能說明書盡可能詳細等等。如果這些文檔都被要求寫的話，保持它們同步比進行一個戰役還痛苦。
為何不把這些信息保存在一個地方呢？？最明顯想到的地方就是代碼的注釋中；但是你很難通覽程序，并且有些需要這些文檔的人并不懂編碼。最好的辦法是通過使用XML注釋來解決這些問題。代碼注釋、用戶手冊、開發人員手冊、測試計劃等很多文檔可以很方便的從XML注釋中獲得。本文講解.Net中經常使用的XML注釋.主要使用C#語言.Net平臺支持的其他語言使用的XML注釋格式基本相同.并且在本系列文章的下一講中講解如何使用工具將XML注釋內容轉化為幫助文檔.
代碼注釋規范需要使用以三個斜杠 (///) 開始注釋，這些注釋后面必須緊跟它們所注釋的用戶定義類型（如類、委托或接口）或者成員（如字段、事件、屬性或方法）.對注釋解說需要使用有效的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#規范中所有的標記列出來，遺失的部分只能用手工插入。 這些手工標記是非常有用的，如果恰當地設置他們，對導出成外部說明文件將非常有幫助。
注釋的使用很簡單,但是我們使用到的注釋很少.這是因為大部分項目中注釋的作用僅僅是給程序員自己看.如果想要生成類似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> |
需要注意的幾點:
1) 最開始seealso標簽添加在了remarks標簽中,所以在See Also區域沒有添加上方法的連接. 解決方法是把seealso標簽放在summary標簽中.
2) 異常類的cref屬性需要設置成編譯器可以識別的類, 這樣才可以在幫助文檔中點擊.比如上面的System.ApplicationException異常點擊后進入微軟的在線MSDN查詢.如果是自己定義的異常, 需要此異常類也在你的幫助文件中.一般提供注釋XML和依賴DLL即可.
屬性的注釋也很簡單.和類不同的地方在于屬性要使用<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
文章中的部份圖片來源網絡的圖片，版權歸相關圖片的所有者。
如果圖片有對您造成影響，可聯系我處理。
免責聲明：本站發布的內容（圖片、視頻和文字）以原創、轉載和分享為主，文章觀點不代表本網站立場，如果涉及侵權請聯系站長郵箱：is@yisu.com進行舉報，并提供相關證據，一經查實，將立刻刪除涉嫌侵權內容。
