NDoc: How to Make Good Use of Your XML Comments?

NDoc: How to Make Good Use of Your XML Comments?

NDoc: How to Make Good Use of Your XML Comments?

 

Written by Allen Lee

Requirement

• 使用C#進行庫的開發。
• 在源代碼裏使用XML註釋。
• 厭倦額外的文檔編制工作，希望有無怨無悔的電腦接手這份枯燥無味的工作。
• 具備C#的開發條件，至少需要.NET Framework SDK 1.1。
• 能儘量抑制你的瞌睡蟲，不讓它阻礙你閱讀本文。
• 其它...

 

Encountered Problems

• 面向對象技術的普及，爲我們帶來了極大的便利。對象的重用減輕了我們編碼時許多不必要的痛苦，清晰的代碼責任分離制免除了我們每頓都要面對着“意大利粉”的厭惡。
• 但是，我們仍然要面對着枯燥的文檔編制——從內容構思到頁面排版。相信庫開發人員對這種厭惡已經深有感觸，即使我們都承認文檔的重要性。 當然，某些大企業有專人寫文檔，但最瞭解庫的卻是程序員自己！而程序員往往又會在自己開發的庫中爲代碼添加註釋，如果有個工具能夠利用這些註釋按照一定的格式要求直接導出文檔該多好呀！
• 聰明而“懶惰”的程序員總是比其他人先行一步，他們不願把自己放進重複而枯燥的方框內，他們千方百計要跳出這個方框，讓自己能夠從事更富創造性的活動，把這些枯燥無味的扔給無怨無悔的電腦們。

 

Feel Free to Write Your Class Library With XML Comments Added

• 單純的文字無法讓你領略NDoc的魅力，至少我還沒有這個能力。睡着了嗎？（或許周公的故事更加有趣！）還沒有的話請看看下面這段示範代碼——一個表示複數的類（class）。

using System;
using System.Globalization;

namespace MathUtils
{
    /**//// <summary>
    /// 提供複數的相關操作服務。
    /// </summary>
    public sealed class Complex
    {
        /**//// <summary>
        /// 默認構造器，將複數的實部與虛部分別設置爲0；
        /// </summary>
        public Complex()
        {
            _Real = 0;
            _Imaginary = 0;
        }

        /**//// <summary>
        /// 分別將複數的實部與虛部設置爲指定的值。
        /// </summary>
        /// <param name="real"></param>
        /// <param name="imaginary"></param>
        public Complex(int real, int imaginary)
        {
            _Real = real;
            _Imaginary = imaginary;
        }

        private int _Real;
        /**//// <summary>
        /// 複數的實部。
        /// </summary>
        public int Real
        {
            get
            {
                return _Real;
            }
            set
            {
                _Real = value;
            }
        }

        private int _Imaginary;
        /**//// <summary>
        /// 複數的虛部。
        /// </summary>
        public int Imaginary
        {
            get
            {
                return _Imaginary;
            }
            set
            {
                _Imaginary = value;
            }
        }

        /**//// <summary>
        /// 把複數轉換爲對應的字符串形式。
        /// </summary>
        /// <returns>
        /// 返回(X)+(Y)i的形式的字符串。
        /// </returns>
        public override string ToString()
        {
            return String.Format(CultureInfo.InvariantCulture,
            "{0} + {1}i",
            _Real,
            _Imaginary);
        }

    }
}

 

Generate Your XML Comments to A Seperate XML File

• 如果你有Visual C# .NET，那麼你可以輕鬆的使用一下的步驟：在解決方案管理器中右鍵單擊該項目圖標，依次選擇 屬性 | 配置屬性 | 生成，在 [輸出] 的 [XML 文檔文件] 右邊填入目標XML文件的文件名，這裏是Complex.xml。保存設置並關閉該對話框，生成該項目，你將會在項目的根目錄中找到這個XML文件。

• 沒有Visual C# .NET？沒所謂，用C#的命令行編譯器CSC.exe也可以。只需要在源代碼所在的目錄的命令提示符下鍵入csc /t:library /doc:Complex.xml Complex.cs<Enter>（詳細請參見下面的評論），就可以生成XML註釋文件了。
• 好了，現在來看看我們第一階段的勞動成果：

<?xml version="1.0" encoding="utf-8" ?> 
<doc>
    <assembly>
        <name>Complex</name>
    </assembly>
    <members>
        <member name="T:MathUtils.Complex">
            <summary>
            提供複數的相關操作服務。
            </summary>
        </member>
        <member name="M:MathUtils.Complex.#ctor">
            <summary>
            默認構造器，將複數的實部與虛部分別設置爲0；
            </summary>
        </member>
        <member name="M:MathUtils.Complex.#ctor(System.Int32,System.Int32)">
            <summary>
            分別將複數的實部與虛部設置爲指定的值。
            </summary>
            <param name="real"></param>
            <param name="imaginary"></param>
        </member>
        <member name="M:MathUtils.Complex.ToString">
            <summary>
            把複數轉換爲對應的字符串形式。
            </summary>
            <returns>
            返回(X)+(Y)i的形式的字符串。
            </returns>
        </member>
        <member name="P:MathUtils.Complex.Real">
            <summary>
            複數的實部。
            </summary>
        </member>
        <member name="P:MathUtils.Complex.Imaginary">
            <summary>
            複數的虛部。
            </summary>
        </member>
    </members>
</doc>

 

Where Is Our Protagonist?

• 現在是時候輪到這齣戲的主角出場了——NDoc。接下來...下載...安裝...啓動NDoc...（是否人類總不能擺脫枯燥無味呢？）按下 [Add] 來添加你的Dll或Exe，以及與之相關聯的XML註釋文件。

• 你希望NDoc用什麼樣的格式來生成庫文檔呢？喲，可供選擇的類型也不少嘛！我們試試MSDN吧！

• 好了，萬事俱備，只欠生成。Now build it!

• Well done! 這就是我們的第二階段成果，也就是最終成果了！有沒有覺得手癢想試一下呢？

 

Conclusion

• 終於大結局啦，一百個人就有一百個哈姆雷特，不知道NDoc在你心目中是怎麼一個形象呢？
• 不知道你是否認爲NDoc偏心，只對能使用XML Comments的C#這麼好。然而，VB.NET也不需要感到難過，因爲你有個VBCommenter在背後默默的支持你呢！