三把利器快速製作代碼協助文檔

1、前言

相信不少麻油都已經積累了屬於自己的程式碼程式庫了，不知道是否有過這樣的經曆：

A:聽說你上次寫了個通用XXX類庫啊，我正好要用到，麻煩把dll發我一下。

B:好的，你等一下，我發給你。。。

。。。十分鐘後

A:喂，你這個類是怎麼用的啊，有沒有協助文檔啊。

B:汗，沒來得及做，我來和你說吧。。。

一個好用的類庫，如果能配上一個好的說明文檔（最好還帶搜尋功能），無疑是為自己和他人提供了莫大的方便，有什麼想要的功能，去文檔裡一查，一目瞭然。

我最近就碰到了這個問題，甚至更為嚴重的是，有很多很久之前寫的代碼，裡面實現了哪些功能，細節我已經不是很清楚了，還需要去翻看代碼，非常難管理和尋找。

2、準備

那麼開始今天的內容，首先需要準備好三大利器啊^_^：

一、下載安裝GhostDoc:http://submain.com/download/ghostdoc/

二、下載安裝sandcastlehttp://sandcastle.codeplex.com/和Sandcastle Help File Builderhttp://shfb.codeplex.com/

三、安裝Visual Studio（什嗎？這個誰沒有？好吧，咱們繼續往下-
-||)

3、開始

下面說一下三大利器到底怎麼配合用，幫我們製造出好用的協助文檔呢？

一、給代碼添加XML注釋

不知道大家通常是怎麼寫注釋的，我的習慣都是直接///然後vs幫我產生XML格式的注釋，而不是簡單的//或者/**/。現在有了GhostDoc(大家也可以下載GhostDoc
Pro,可以批量注釋，更強大)，我們就可以快速的給我們的代碼添加註釋了。

這一步是必不可少的，否則文檔就沒有了資料來源了。

如果GhostDoc不會用，可以參考這個文章，總結的很詳細：http://www.cnblogs.com/RockyMyx/archive/2010/04/20/Project-Route-Using-GhostDoc.html

二、整理專案檔

這一步是做什麼呢？其實主要是利用VS強大的“產生後事件”功能，配置一些宏和Marco指令，把我們程式碼程式庫中的dll和注釋檔案xml拷貝到一起，方便製作。當然，如果您的代碼全寫在一個項目dll裡，那這一步對您來說是沒什麼用處啦。反正我的庫是分了20多重專案，一個個去找dll很麻煩的，所以就自動讓他們放到一個輸出目錄下：

開啟項目屬性：

選擇“產生”面板，允許輸出XML注釋文檔，這步很重要

下面選擇“建置事件”面板，在“產生後事件”中輸入指令：

copy  "$(TargetDir)*.dll"
"$(TargetDir)..\..\..\OutPut"
copy  "$(TargetDir)*.xml"
"$(TargetDir)..\..\..\OutPut"

好了，把整個類庫重建一下，會發現在OutPut檔案夾裡全部是我們要的dll和Xml:

三、使用Sandcastle Help File
Builder建立協助文檔項目

開啟Sandcastle Help File Builder，後面的具體步驟可以參考這篇文章：http://www.cnblogs.com/RockyMyx/archive/2010/04/30/Project-Route-Using-SandcastleBuilder.html，也很詳細。按照步驟一步步做，就可以成功產生協助文檔了。

4、效果

下面看一下效果：