.NET开发：NDoc: Make good use of your XML Comments.

热点排行

NDoc: Make good use of your XML Comments.

类别：.NET开发点击：0 评论：0 推荐：

本专题主要介绍Allen Lee在平时的工作和学习中遇到的好的.NET工具，并讲述相关的使用经验。工欲善其事，必先利其器。那么，现在就让我们看看有什么器可以利吧！

1. 喜欢C#的朋友一定见识过C#的XML文档注释（XML Comments），但是我们可能还没有充分利用这一项功能，顶多，我们仅仅把它跟其他类型的注释等同起来，在代码的页面给出一些说明或者代码功能描述，充其量只是新颖一点，正式的代码描述文档工作还是要另外用Word或者什么来处理。慢着！有没有想过这两者可以结合一起？我的意思是，在源代码上面进行注释，然后直接导出到XML，再加上一些处理成为HTML文档？为了说明问题，我写了一个简单的代码：

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);
        }

    }
}

如果你有Visual C# .NET，那么你可以轻松的使用一下的步骤：在解决方案管理器中右键单击该项目图标，选择属性 |?配置属性 | 生成，在[输出]的[XML 文档文件]右边填入目标XML文件的文件名，这里采用Complex.xml。保存设置并关闭该对话框，生成该项目，你将会在项目的根目录中找到这个XML文件。

如果你没有Visual C# .NET，你大可以使用命令行界面以及CSC.exe，只需要在源代码所在的目录的命令提示符下键入csc Complex.cs /doc:Complex.xml[Enter]，就可以生成XML注释文件了。下面看看生成的文件：

<?xml version="1.0"?>
<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>

接下来我们怎么利用这个生成的XML呢？很简单使用我们这次介绍的主角——NDoc，先去http://ndoc.sourceforge.net/下载，安装，然后运行NDoc。点击Add添加生成的Dll或者Exe程序集，以及相关的XML文档文件。然后选择Build来生成文档文件，而且生成的文件还可以选择类型。

就这样，我们就生成了一个文档，这里我选择MSDN文档类型：

可以问你一个问题吗？当你看完这篇介绍后，你有没有想过使用这个工具？有多想？能给我一个回复么？（完全没兴趣、感觉无所谓、有机会可以一试、马上去下载一个看看）谢谢！

Allen Lee