生成類庫chm幫助文檔

生成類庫chm幫助文檔

目 錄

第一章配置說明3

1.1本地服務器信息3

第一章 
生成文檔說明

一.1 生成幫助文檔的作用

項目開發(fā)與各部門配合時,給他們提供一個外部服務,既然是提供給別人（研發(fā)、測試等）使用的,當然需要告訴別人怎么來用你的服務,這也就是我們常說的技術文檔。各組之間傳遞技術文檔的方式有很多種。這里我知道的大概有以下幾種：

    第一：口頭傳遞技術文檔，也就是沒有實質的文檔資料，口頭說明一下即可，這種情況局限于溝通起來非常方便的開發(fā)團隊中，例如就坐在一個辦公間等等。

    第二：以文本形式，把如何使用的技術點記錄下來，這個方法有什么用，那個屬性是做什么的等等，這種方式無疑是表述最清楚的，單獨的文檔中你甚至可以用圖的方式教導使用者，但缺點就是維護起來相當麻煩，而且費時。如果哪天服務的實現有了比較大的改變，那更新這個文檔就非常麻煩了。

    第三：利用工具，配合.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 的網站。它只需要您簡單的作出幾個設置，就能非常方便的幫助您生成專業(yè)的，帶有高級語法過濾、語法高亮、搜索和導航功能全功能站點。

總結：Sandcastle Help File Builder能夠非常好的和VS合作，制作出MSDN風格的幫忙文檔，即有效的對項目保存了技術文檔又降低了溝通成本。

第二章 Sandcastle Help File Builder說明

二.1 SHFB的軟件環(huán)境

下載地址：

下載后解壓縮到目錄：

二.2 SHFB安裝過程

二.3 安裝步驟

按步驟進行安裝

二.4 配置項目中生成xml文檔

二.5 創(chuàng)建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文檔

第三章 注釋文檔規(guī)范

三.1 注釋的必要性

.Net允許開發(fā)人員在源代碼中插入XML注釋，這在多人協作開發(fā)的時候顯得特別有用。 C#解析器可以把代碼文件中的這些XML標記提取出來，并作進一步的處理為外部文檔。 這篇文章將展示如何使用這些XML注釋。 在項目開發(fā)中，很多人并不樂意寫繁雜的文檔。但是，開發(fā)組長希望代碼注釋盡可能詳細；項目規(guī)劃人員希望代碼設計文檔盡可能詳盡；測試、檢查人員希望功能說明書盡可能詳細等等。如果這些文檔都被要求寫的話，保持它們同步比進行一個戰(zhàn)役還痛苦。

為何不把這些信息保存在一個地方呢？？最明顯想到的地方就是代碼的注釋中；但是你很難通覽程序，并且有些需要這些文檔的人并不懂編碼。最好的辦法是通過使用XML注釋來解決這些問題。代碼注釋、用戶手冊、開發(fā)人員手冊、測試計劃等很多文檔可以很方便的從XML注釋中獲得。本文講解.Net中經常使用的XML注釋.主要使用C#語言.Net平臺支持的其他語言使用的XML注釋格式基本相同.并且在本系列文章的下一講中講解如何使用工具將XML注釋內容轉化為幫助文檔.

三.2 代碼注釋規(guī)范

代碼注釋規(guī)范需要使用以三個斜杠 (///) 開始注釋，這些注釋后面必須緊跟它們所注釋的用戶定義類型（如類、委托或接口）或者成員（如字段、事件、屬性或方法）.對注釋解說需要使用有效的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#規(guī)范中所有的標記列出來，遺失的部分只能用手工插入。 這些手工標記是非常有用的，如果恰當地設置他們，對導出成外部說明文件將非常有幫助。

三.3 常見注釋標簽列表

注釋的使用很簡單,但是我們使用到的注釋很少.這是因為大部分項目中注釋的作用僅僅是給程序員自己看.如果想要生成類似MSDN這樣的文檔,我們需要了解更多的注釋標簽.下面是我整理的常用的注釋標簽:

三.4 <Summary>

三.5 類注釋

三.6 方法注釋

需要注意的幾點:

1) 最開始seealso標簽添加在了remarks標簽中,所以在See Also區(qū)域沒有添加上方法的連接. 解決方法是把seealso標簽放在summary標簽中.

2) 異常類的cref屬性需要設置成編譯器可以識別的類, 這樣才可以在幫助文檔中點擊.比如上面的System.ApplicationException異常點擊后進入微軟的在線MSDN查詢.如果是自己定義的異常, 需要此異常類也在你的幫助文件中.一般提供注釋XML和依賴DLL即可.

三.7 屬性注釋

屬性的注釋也很簡單.和類不同的地方在于屬性要使用<value>標簽而不是<remarks>進行描述

第四章 參考資料

1、 使用SandCastle創(chuàng)建.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

文章中的部份圖片來源網絡的圖片，版權歸相關圖片的所有者。 

 如果圖片有對您造成影響，可聯系我處理。