DotNet 项目开发文档的自动生成和相关工具的使用

DotNet 项目开发文档的自动生成和相关工具的使用

在 VS.Net 的 IDE 中对C#提供了一些可以自动生成的 XML 注释，使用这些注释可以对代码中定义的对象进行说明、注解；通过设置项目属性，在生成项目时，可以让VS.Net自动的将这些注释信息输出到 XML 文件中，这些 XML 文档可以用文档自动生成工具 NDoc 转换为 MSDN 格式的 html 文件，并自动编译为 CHM 文件。

对于 C# 项目，在 VS.Net 的 IDE 中，通过在类、方法、属性等前通过输入“///”可自动生成 XML 注释框架，在框架中直接填写内容即可。

举例如下：

在SampleNameSpace命名空间中定义了一个Sample类，该类除构造器外有一个SomeEvent事件，则对该类和事件的说明如下：

using  System;

namespace  SampleNamespace
{
    /**//// <summary>
    /// Sample 类的摘要说明。
    /// </summary>
    /// <remarks>用 remarks 标签书写备注</remarks>
    /// <example>这是例子说明</example>
    public class Sample
    {
        /**//// <summary>
        /// 对构造器的说明
        /// </summary>
        public Sample()
        {
            //
            // TODO: 在此处添加构造函数逻辑
            //
        }

        /**//// <summary>
        /// 对函数/过程的摘要说明
        /// </summary>
        /// <param name="StringParam">对参数 StringParam 的说明</param>
        /// <param name="IntParam">对参数 IntParam 的说明</param>
        /// <returns>对返回值的说明</returns>
        public Boolean SomeEvent(string StringParam,Int32 IntParam)
        {
            //
            //函数/过程内容
            //
            return true;
        }
    }
}

以上代码中“///”后面的注释内容中，所有的 XML 标签都是由 IDE 自动产生的，只需要填写内容即可。

除了上面使用到的标签外，NDoc 还支持其他的一些标签，参见 NDoc 支持的文档注释标记。

对于VB.Net项目，IDE 需要安装一个第三方工具 VBCommenter 后才支持 XML 注释的自动生成，安装后通过输入“'''”回车，即可自动生成 XML 注释框架。

项目生成过程中默认不会生成包含项目 XML 注释信息的 XML 文档，需要对项目进行配置：打开项目，选择菜单“项目”→“xxxx项目属性”→“配置属性”→“生成”→“XML 文档文件”，在这里填写要输出的 XML 文件名。

以上的配置说明适用于 C# 项目，VB.Net 项目需要安装 VBCommenter 并选中“Create .xml files when projects are built”选项， VBCommenter 不允许自己设定输出 XML 文件名，输出的 XML 文件名称默认为 项目名称 + ".xml"。

做了以上的配置后，在生成项目时就会自动的把填写在源代码中的 XML 注释输出到指定文件中。

在输出到 XML 文件后，就可以用 NDoc 来生成项目开发文档了。

NDoc 是一个基于 GPL 协议的开源项目，其主页为http://sourceforge.net/projects/ndoc/，目前最新版本为 v1.3 Beta1a。

运行 NDocGui.exe 文件打开 NDoc，点击菜单“Project”→“New from Visual Studio Solution”选择一个 Visual Stucio 解决方案并为其创建一个新的 NDoc 项目，然后选择要添加到项目中的程序集：点击“Add”按钮选择程序集文件名和对应该程序集文件的 XML 注释信息文档文件名，点击 OK 即可添加到项目中，重复以上步骤将所有要生成文档的程序集加入到NDoc项目中。

窗口的下方是 NDoc 项目属性设置部分，使用方法和 Visual Studio.Net 的属性窗口相同，每个属性都在下面有简单介绍，可以在这里对最终生成的 CHM 文档的外观、版权信息等信息进行设置。

最终生成的文档格式有多种选择，包括 JavaDoc、LaTeX、LinearHtml、MSDN、XML 五种，我们一般采用 MSDN 格式生成 html 文档并将其编译为 CHM文件。

设置完成后点击“Build Documentation”按钮即可生成 html 文档并将其编译为 CHM 文件。

对 NDoc 项目的设置可以保存为 .ndoc 配置文件，NDoc 还提供了一个 NDocConsole.exe 文件，使用这个文件可以在命令行下完成 NDoc 项目的编译工作，这样就在持续构建过程中提供了一个简单的方法来完成文档的自动生成工作。

posted on 2004-09-07 16:34  NetCobra 阅读( ...) 评论( ...) 编辑 收藏

转载于:https://www.cnblogs.com/NetCobra/archive/2004/09/07/40755.html