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

?

Written by Allen Lee

Requirement

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

?

Encountered Problems

• 面向?qū)ο蠹夹g(shù)的普及，為我們帶來了極大的便利。對象的重用減輕了我們編碼時許多不必要的痛苦，清晰的代碼責任分離制免除了我們每頓都要面對著“意大利粉”的厭惡。
• 但是，我們?nèi)匀灰鎸χ菰锏奈臋n編制——從內(nèi)容構(gòu)思到頁面排版。相信庫開發(fā)人員對這種厭惡已經(jīng)深有感觸，即使我們都承認文檔的重要性。 當然，某些大企業(yè)有專人寫文檔，但最了解庫的卻是程序員自己！而程序員往往又會在自己開發(fā)的庫中為代碼添加注釋，如果有個工具能夠利用這些注釋按照一定的格式要求直接導出文檔該多好呀！
• 聰明而“懶惰”的程序員總是比其他人先行一步，他們不愿把自己放進重復而枯燥的方框內(nèi)，他們千方百計要跳出這個方框，讓自己能夠從事更富創(chuàng)造性的活動，把這些枯燥無味的扔給無怨無悔的電腦們。

?

Feel Free to Write Your Class Library With XML Comments Added

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

using?System;
using?System.Globalization;

namespace?MathUtils
{
????/**////?<summary>
????///?提供復數(shù)的相關(guān)操作服務(wù)。
????///?</summary>
????public?sealed?class?Complex
????{
????????/**////?<summary>
????????///?默認構(gòu)造器，將復數(shù)的實部與虛部分別設(shè)置為0；
????????///?</summary>
????????public?Complex()
????????{
????????????_Real?=?0;
????????????_Imaginary?=?0;
????????}

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

????????private?int?_Real;
????????/**////?<summary>
????????///?復數(shù)的實部。
????????///?</summary>
????????public?int?Real
????????{
????????????get
????????????{
????????????????return?_Real;
????????????}
????????????set
????????????{
????????????????_Real?=?value;
????????????}
????????}

????????private?int?_Imaginary;
????????/**////?<summary>
????????///?復數(shù)的虛部。
????????///?</summary>
????????public?int?Imaginary
????????{
????????????get
????????????{
????????????????return?_Imaginary;
????????????}
????????????set
????????????{
????????????????_Imaginary?=?value;
????????????}
????????}

????????/**////?<summary>
????????///?把復數(shù)轉(zhuǎn)換為對應(yīng)的字符串形式。
????????///?</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。保存設(shè)置并關(guān)閉該對話框，生成該項目，你將會在項目的根目錄中找到這個XML文件。

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

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

?

Where Is Our Protagonist?

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

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

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

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

?

Conclusion

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

?

轉(zhuǎn)載于:https://www.cnblogs.com/allenlooplee/archive/2004/10/24/56181.html

總結(jié)

以上是生活随笔為你收集整理的NDoc: How to Make Good Use of Your XML Comments?的全部內(nèi)容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網(wǎng)站內(nèi)容還不錯，歡迎將生活随笔推薦給好友。