2011年6月27日 星期一

[.Net] C#的註解方式以及XML的說明文件

這篇是延續上一篇,要使用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)

延伸閱讀:

2 則留言: