簡介
雖說 Visual Studio.Net 已經可以為 c# 程式製作說明文件,但是如果不想安裝這個龐然大物,卻又想要享受這樣的便利,那麼該怎麼辦呢??
其實,.Net Framework 內的 compiler: csc 已經具有這樣的選項.只要在編譯的時候指定了這個選項,那麼,compiler就會自動將程式中我們依照規定所加上的註解擷取為一個 xml 檔案,裡面就是說明文件啦~~
那麼,什麼是”依照規定所加上的註解”呢??
原來這個東西的正名應該是[XML Documentation in C#].它是一份由微軟所訂定的白皮書,裡面載明應該要怎麼註解.
他最主要的用意是讓開發者能夠為程式做一些註解,而不必在程式整個完成之後才去做 API 說明文件這個苦工.像是 Java, C/C++…等等都有類似的工具可以幫忙做掉這件事.
安裝
首先,我們得先安裝微軟的 HTMLHelp 工具,這工具主要是被 ndoc 用來將html 檔轉換為 chm 檔案.
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
如果你想要在 Visual Studio.Net 內使用的話,你需要再安裝 Integration Kit.
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwmscextendingnethelp.asp
接著再到 http://ndoc.sourceforge.net 下載 ndoc
http://ndoc.sourceforge.net/wiki/Download_NDoc
在這裡我們直接下載已經包裝好的安裝程式來安裝,省掉自行編譯的麻煩.
http://prdownloads.sourceforge.net/ndoc/NDocSetup.Exe?download
這邊要特別注意的是,安裝時,必須要能上網連到外面去,因為安裝程式會自動去下載最新版本的 NDocSetup.msi ,然後再安裝.如果你無法上網,那麼就請先將
http://ndoc.sourceforge.net/setup/NDocSetup.msi
下載下來,然後以滑鼠右鍵點選 NDocSetup.msi, 選安裝,同樣也可以安裝.
使用
下面我們就來看看要怎麼使用這個工具吧~
在安裝完成之後,接下來就是乖乖的為程式加上註解啦,這裡以一個簡單的 Hello world 程式作為範例.
using System;
/// <summary>
/// 主程式類別
/// </summary>
public class MainProg
{
/// <summary>
/// 印出 Hello world 字串.
/// </summary>
/// <remarks>
/// <para>
/// 印出 Hello world 字串.
/// </para>
/// <para>
/// 向 <c>strName</c> 問候 Hello world.
/// </para>
/// </remarks>
/// <param name=”strName”>姓名</param>
public static void sayHello( string strName )
{
Console.WriteLine(“Hello world!! ” + strName );
}
/// <summary>
/// 主程式
/// </summary>
/// <param name=”args”>程式引數</param>
public static void Main( string[] args )
{
sayHello(“RUN!PC”);
}
}
將程式存到 c:\tmp 下並命名為 hello.cs 之後,接著請打開”命令提示字元”,依序輸入
cd c:\tmp
csc /doc:hello.xml /target:exe /out:hello.exe hello.cs
編譯完成後,你會發現多出 hello.exe 與 hello.xml
這裡加上 /doc:hello.xml 就是為了要讓 compiler 將註解輸出到 hello.xml, ndoc 會用到這個檔案.
接著,請打開 ndoc, 你會看到如圖二的畫面.
按下 Add, 然後將我們剛剛編譯出來的 hello.exe 和 hello.xml 加入,選擇 ok.如圖三.
接著你會發現 hello.exe 出現在畫面上,如圖四.
下面有一些屬性可以調整,例如標題列要出現的文字,輸出路徑,輸出檔名…等等.
這裡我們將輸出路徑(OutputPath)指向c:\tmp\doc\,並將 HtmlHelpName 改為 Hello.
接著,按下 Build (圖四紅色筆框起來的按鈕)
Build 會花一些時間(視專案大小而定),這段期間 ndoc 會開啟 hello.exe 這個 assembly 和 hello.xml,並利用 xslt 來將 xml 轉換為 html 檔案,再呼叫 HtmlHelp 來編譯為 .chm 檔案.
編譯完成後,你可以直接點選工具列最右邊的按鈕(像放大鏡的那個)來查看編譯後的成果.如圖五.
我第一次製作成功的時候,心裡蠻感動的,因為只要在寫程式的時候,多花一點心力去註解,就可以這麼樣地省力製作出一份 API 文件.
我們可以去瀏覽一下 c:\tmp\doc 這個資料夾,你會發現裡面有大量的 html 與圖片檔,這正證明了 ndoc 會先轉換為 html 之後,再交由 HtmlHelp 去編譯為 .chm 檔案.(如圖六)
XML Documentation tags
除了我們剛剛有使用到的 summary, remarks, param, para, c 之外,還有提供許多 tag 可以用來標明,以下簡單說明如下:
| tag 名稱 | 用途 |
| c | 讓包起來的文字字體與程式碼相同 |
| code | 表示程式碼 |
| example | 如何使用這個類別或函數的簡單範例 |
| exception | 描述例外處理 |
| list | 表列 |
| para | 表示被包起來的文字是一個段落 |
| param | 對參數的說明 |
| paramref | 表示直接連結到某參數的說明 |
| permission | 權限的描述 |
| remarks | 用來作詳細描述 |
| returns | 對回傳值的說明 |
| see | 指定一個連結 |
| seealso | 表示可以另行參考的項目 |
| summary | 最常見的,用來簡單描述用途 |
| value | 描述屬性的值 |
ndoc 本身也有擴充一些 tag,這部分讀者可以自行到 ndoc 官方網站去尋找相關資料.
不過我相信 XML Documentation 的定義應該是足夠應付大部分的狀況了.
參考資料
ndoc 官方網站:
http://ndoc.sourceforge.net
文件參考:
XML Documentation in C# http://www.gotdotnet.com/team/csharp/learn/whitepapers/XMLDocs.doc
相關軟體下載:
HTML Help: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
Integration Kit:http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwmscextendingnethelp.asp
Ndoc: http://ndoc.sourceforge.net/wiki/Download_NDoc
延伸閱讀:
http://ndoc.sourceforge.net/wiki/NDoc_Articles