NDoc使用简要手册

UML软件工程组织

火龙果软件工程技术中心

更多技术资源文章，讲座 ,培训，咨询请访问 www.uml.org.cn

NDoc使用简要手册

2008-09-08 来源：网络

NDoc是一个.NET代码文档生成工具，有点象JDoc,但这个是在.NET下的工具。

NDoc使用Visual Studio.NET开发过程中生成的程序集和XML文档来生成一些格式象Visual Studio.NET和.NET Frmaework SDK在线帮助文档那样的一些编译后的HTML帮助文档。

它是一个OpenSource的项目，在http://ndoc.sourceforge.net可以下载到SourceCode。

使用十分简单，例如创建一个简单的项目来看NDoc可以为我们做些什么？

创建一个简单项目叫testNDoc，只有一个WindowForm，上面有个Button,单击显示信息。

将显示信息的类封装为ShowMsg类，只有一个方法ShowMessage.

代码如下：

showMsg.cs

using System;

using System.Windows.Forms;

namespace testNDoc
{
    /// <summary>
    /// ShowMsg 的摘要说明。
    /// 显示测试信息的类
    /// </summary>
    public class ShowMsg
    {
        public ShowMsg()
        {
            //
            // TODO: 在此处添加构造函数逻辑
            //
        }
        /// <summary>
        /// 测试字符串
        /// </summary>
        private string testStr = null;



        /// <summary>
        /// 增加几个字符的私有函数
        /// </summary>
        /// <param name="msg">传递字符串参数</param>
        /// <returns>返回处理过的字符串</returns>
        protected string addStr(string msg)
        {
           // 返回字符串
            return "StrAdd:" + msg;
        }

      /// <summary>
        /// test addOk
        /// </summary>
        /// <param name="msg"></param>
        /// <returns></returns>
        protected string addOk(string msg)
        {
            return "Ok:" + msg;
        }
    }
}

Form1.cs

using System;

using System.Drawing;

using System.Collections;

using System.ComponentModel;

using System.Windows.Forms;

using System.Data;

namespace testNDoc
{
    /// <summary>
    /// Form1 的摘要说明。
    /// </summary>
    public class testNDoc : System.Windows.Forms.Form
    {
        private System.Windows.Forms.Button btnShowMsg;
        private System.Windows.Forms.Button btnNoSummary;
        /// <summary>
        /// 必需的设计器变量。
        /// </summary>
        private System.ComponentModel.Container components = null;

        public testNDoc()
        {
            //
            // Windows 窗体设计器支持所必需的
            //
            InitializeComponent();

            //
            // TODO: 在 InitializeComponent 调用后添加任何构造函数代码
            //
        }

        /// <summary>
        /// 清理所有正在使用的资源。
        /// </summary>
        protected override void Dispose( bool disposing )
        {
            if( disposing )
            {
                if (components != null)
                {
                    components.Dispose();
                }
            }
            base.Dispose( disposing );
        }

        Windows 窗体设计器生成的代码
        /// <summary>
        /// 设计器支持所需的方法 - 不要使用代码编辑器修改
        /// 此方法的内容。
        /// </summary>
        private void InitializeComponent()
        {
            this.btnShowMsg = new System.Windows.Forms.Button();
            this.btnNoSummary = new System.Windows.Forms.Button();
            this.SuspendLayout();
            //
            // btnShowMsg
            //
            this.btnShowMsg.Location = new System.Drawing.Point(72, 104);
            this.btnShowMsg.Name = "btnShowMsg";
            this.btnShowMsg.Size = new System.Drawing.Size(128, 32);
            this.btnShowMsg.TabIndex = 0;
            this.btnShowMsg.Text = "ShowMsg";
            this.btnShowMsg.Click += new System.EventHandler(this.btnShowMsg_Click);
            //
            // btnNoSummary
            //
            this.btnNoSummary.Location = new System.Drawing.Point(72, 160);
            this.btnNoSummary.Name = "btnNoSummary";
            this.btnNoSummary.Size = new System.Drawing.Size(128, 32);
            this.btnNoSummary.TabIndex = 1;
            this.btnNoSummary.Text = "No Summary";
            this.btnNoSummary.Click += new System.EventHandler(this.btnNoSummary_Click);
            //
            // testNDoc
            //
            this.AutoScaleBaseSize = new System.Drawing.Size(6, 14);
            this.ClientSize = new System.Drawing.Size(520, 341);
            this.Controls.Add(this.btnNoSummary);
            this.Controls.Add(this.btnShowMsg);
            this.Name = "testNDoc";
            this.Text = "testNDoc";
            this.ResumeLayout(false);

        }
        #endregion

        /// <summary>
        /// 应用程序的主入口点。
        /// </summary>
        [STAThread]
        static void Main()
        {
            Application.Run(new testNDoc());
        }

        /// <summary>
        /// 单击button显示信息
        /// </summary>
        /// <param name="sender"></param>
        /// <param name="e"></param>
        private void btnShowMsg_Click(object sender, System.EventArgs e)
        {
            ShowMsg sMsg = new ShowMsg();
            sMsg.ShowMessage("Hello?");
        }

        private void btnNoSummary_Click(object sender, System.EventArgs e)
        {
            ShowMsg sMsg = new ShowMsg();
            sMsg.ShowMessage("No Summary Click!");
        }
    }
}

为了使用NDoc生成文档，必须有一个编译后的程序集和一个导出的XML文件，要生成这个XML文件，必须在项目属性中将生成XML文件的

选项填上文件名字，如下图：

编译有生成一个对应的XML文件：

打开XML文件看到以下内容(注意：这个XML文件并不是NDoc生成的，而是Visual Studio.NET生成的)：

<?xml version="1.0"?>

<doc>

<name>testNDoc</name>

</assembly>

Form1 的摘要说明。

</summary>

</member>

必需的设计器变量。

</summary>

</member>

清理所有正在使用的资源。

</summary>

</member>

设计器支持所需的方法 - 不要使用代码编辑器修改

此方法的内容。

</summary>

</member>

应用程序的主入口点。

</summary>

</member>

单击button显示信息

</summary>

</member>

ShowMsg 的摘要说明。

显示测试信息的类

</summary>

</member>

测试字符串

</summary>

</member>

显示信息在信息框中的公有函数

</summary>

<param name="msg">传递字符串参数</param>

</member>

增加几个字符的私有函数

</summary>

<param name="msg">传递字符串参数</param>

<returns>返回处理过的字符串</returns>

</member>

test addOk

</summary>

</member>

</members>

</doc>

仔细对比这个XML文件和源代码之间的关系可以发现：

1.这个XML文件列出了大部分的方法，不管这些方法是私有，公有还是保护的，甚至构造函数；

2.region的部分并没有列入XML文件;

3.没有带注释的方法也没有列入XML文件，例如ShowMsg的构造函数和Form1.cs中的btnNoSummary_Click函数部分；

4.有注释的变量也被列入XML文件了，例如Form1.cs中的private System.ComponentModel.Container components = null和ShowMsg类

中的private string testStr = null;5.对于//这种方式的注释并没有例如文件；

小结：以下面方式的注释会列入XML文件中

        /// <summary>
        /// 增加几个字符的私有函数
        /// </summary>
        /// <param name="msg">传递字符串参数</param>
        /// <returns>返回处理过的字符串</returns>

那么NDoc处理后又是如何的呢？

安装NDoc后运行程序，选择程序集和对应的XML文件,如下图

然后就设置生成文档的相关参数了

文档类型目前支持6种：
HtmlHelp2 注意，这种文档需要安装Visual Studio Help Integration Kit，可以在微软网站下载；
JavaDoc 类似于Java API的文档方式，习惯看Java API的人比较喜欢
LaTeX (alpha)
LinearHtml (alpha)
MSDN
XML

选择不同的文档类型需要设置一些不同的参数，这里选择HtmlHelp2格式。

可以设置的参数比较多，很多可以使用默认值，每个的作用都可以在下面看到它的解释，这个例子选择的设置如下图：

选择菜单上的Documentation->Build就可以生成需要的帮助文档了。

此时就会在NDoc文件所在目录下生成一个doc目录，全部生成的文件都放在这个目录下。

打开NDocTest.chm，看到的效果如下：

这里可以看到生成的信息并不是单单依赖于上面讨论的XML文件，也生成了很多完整的信息，这些信息应该通过反射机制在程序集中读取的。

对比结果可以看到：

1.生成的CHM只显示了public和protected，而private则没有显示，不管是否在XML有反应；

2.继承过来的方法也会在CHM中显示出来；

3.生成的CHM主要以程序集为基础，将public和protected的方法显示出来，而XML主要作为注释的参考，例如项目中有些没有注释的共

有方法在XML中没有反应出来，但是在CHM也会显示出来。

小结：NDoc生成的CHM并没有完全将项目中的全部注释抽取出来，但是它作为生成API文档则是十分有用的。

另外值得注意的是：

在使用中发现NDoc的同步似乎有些问题，例如第一次生成后，对有些方法做了些修改，注释的修改可以同步更新，但一些方法的属性变更并没有直接反应过去，例如将public改成protected，在生成的CHM中也不会直接反应。

例子代码可以从这里下载