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在背后默默的支持你呢！