這篇是延續上一篇，要使用Sandcastle產生HelpDoc，必須先在C#中產生XML說明文件(VB.Net也可以用同樣的方法，只是註解寫法有 點不一樣)，而Sandcastle則利用這樣的說明文件去產生HelpDoc，這篇由C#的註解方式講起，簡單說明該如何產生XML說明文件
C#的註解方式以及XML的說明文件
C#提供了兩種註解方法，跟C以及JAVA蠻類似的
單行註解用
//註解
多行則是用
/*
註解
*/
但是以上註解是幫助用來讓Programer了解程式邏輯，只有能看到Source Code的人看得到這些註解，
如果我們要提供API或者library給別人呼叫，就必須提供類似Javadoc的API說明文件，這樣使用者才
會知道這些API的使用方法，以及傳入傳出的參數，而C#的XML註解就可以達到這個功能
C#的XML文件註解方式主要是在souce code中以一般註解的方式加入特定的標籤<tag>，在.Net
Project Build up時，及會同時產生說明文件
大致寫法如下：
/// <summary>
/// Test Project
/// </summary>
public class Test
{
/// <summary>
/// Add two number
/// </summary>
/// <param name="i">1st add number</param>
/// <param name="j">2nd add number</param>
/// <returns>sum</returns>
public int add(int i, int j){
....
}
}
另外也可以寫成這樣用多行註解的形式
/**
<summary>
Test Project
</summary>
*/
多行註解還有很多方式可以用，但是給他有點複雜，詳細可以參考
MSDN裡面的文件標籤的分隔符號 (C# 程式設計手冊)
http://msdn.microsoft.com/zh-tw/library/5fz4y783(v=VS.80).aspx
上面Sample Code用到的Tag
<summary>description</summary>
<summary> 標記應用於描述型別或型別成員。使用 <remarks> 為型別描述加入補充資訊。
<summary> 標記的內容會是 IntelliSense 中有關型別資訊的唯一來源，也會在物件瀏覽器中顯示。
<param name='name'>description</param>
參數 name 為方法參數的名稱。以雙引號 (" ") 將名稱括起來。
<param> 標記應使用於方法宣告的註解中，以描述該方法其中之一的參數。
<param> 標記的文字將會顯示在 IntelliSense、物件瀏覽器和程式碼 Web 註解報告中。
<returns>description</returns>
<returns> 標記應使用於方法宣告的註解來描述傳回值。
上述的標籤可以參考
MSDN建議使用的文件註解標籤 (C# 程式設計手冊)
http://msdn.microsoft.com/zh-tw/library/5ast78ax(v=VS.80).aspx
最後Project要Build前要在Properties中加入指定輸出XML 以下圖例VS2010
例子：
/// <summary>
/// Hello Example
/// </summary>
/// <remarks>
/// Copyright (C) Microsoft Corporation. All rights reserved.
/// </remarks>
public class Hello1
{
/// <summary>
/// Main Function, not a method
/// </summary>
/// <returns>system print out, no return</returns>
public static void Main()
{
Hello1 he1 = new Hello1();
he1.rt_add(1, 2);
System.Console.WriteLine("Hello, World!");
}
/// <summary>
/// Add method
/// </summary>
/// <param name="i">1st num for adding</param>
/// <param name="j">2nd num for adding</param>
/// <returns>return 1st num + 2nd sum</returns>
public int rt_add(int i,int j)
{
return i + j;
}
}
產生出來的結果：
<?xml version="1.0" ?>
<doc>
<assembly>
<name>HelloWorld1</name>
</assembly>
<members>
<member name="T:Hello1">
<summary>Hello Example</summary>
<remarks>Copyright (C) Microsoft Corporation. All rights reserved.</remarks>
</member>
<member name="M:Hello1.Main">
<summary>Main Function, not a method</summary>
<returns>system print out, no return</returns>
</member>
<member name="M:Hello1.rt_add(System.Int32,System.Int32)">
<summary>Add method</summary>
<param name="i">1st num for adding</param>
<param name="j">2nd num for adding</param>
<returns>return 1st num + 2nd sum</returns>
</member>
</members>
</doc>
接著再利用XML以及exe或dll就可以在Sandcastle中產生HelpDoc (.chm)
延伸閱讀：
