注：NDoc是一个Open Source的For .Net 文档自动生成软件。它可以通过 .Net中XML的注释标签来生成非常漂亮的MSDN风格的类库文档。(相对于VS.Net自己带的Comment Web Page生成工具好多了)<?xml:namespace prefix = o />

《在Vs.net中集成 NDoc生成的 Html Help 2帮助文档》

By: Fons Sonnemans

编译：<?xml:namespace prefix = st1 />linkcd

代码下载：NDocSample.zip

简介：

NDoc 可以根据C＃编译器编译出的.Net组件（Assemblies）和XML文档来生成类库的文档。 NDoc可以由附加的文档器（documenter）来生成不同格式的文档，包括MSDN风格的HTML Help File（.chm）， VS.net帮助文档（Html Help2），以及MSDN风格的Web在线文档。

（译注：产生的格式要比VS.net自己由xml tag生成的在线文档好看的多）

本篇文章分4个步骤来介绍如何由NDoc生成类库文档并集成到VS.net中。

1.        使用XML文档标记来注释您所编写的类库

2.        用NDoc来创建HTML Help 2文档

3.        使用H2Reg来注册帮助文档

4.        把帮助文档集成到VSCC

第一步：使用XML文档标记来注释您所编写的类库

我编写了一个简单的库，包括了2个类： Employee 和 EmployeeCollection。这些类都采用了XML风格的注释标签（///）。 这个组件被命名为ReflectionIT.NDocSample。

using System;

namespace ReflectionIT.NDocSample
{
    /// <summary>
    /// Employee class used to demonstrate NDoc and Visual Studio.NET integration.
    /// </summary>
    /// <example>
    /// Some sample:
    /// <code>
    /// Employee emp = new Employee("Jim", 4000);
    /// emp.RaiseSalary();
    /// Console.WriteLine(emp.GetYearSalary);</code>
    /// </example>
    public class Employee
    {
        private string _name;
        private int _salary;

/// <summary>
        /// Initializes a new instance of the Employee class with a name and salary.
        /// </summary>
        /// <param name="name">The name of the employee</param>
        /// <param name="salary">The salary of the employee</param>
        public Employee(string name, int salary)
        {
            this.Name = name;
            this.Salary = salary;
        }

/// <summary>
        /// Gets or sets the name of the employee.
        /// </summary>
        public string Name {
            get { return this._name; }
            set { this._name = value; }
        }

/// <summary>
        /// Gets or sets the salary of the employee.
        /// </summary>
        public int Salary {
            get { return this._salary; }
            set { this._salary = value; }
        }

/// <summary>
        /// Returns the year salary for the employee using 12 months
        /// </summary>
        /// <returns>The year salary</returns>
        public virtual int GetYearSalary() {
            return Salary * 12;
        }

/// <summary>
        /// Raise the salary with 10%
        /// </summary>
        public virtual void RaiseSalary() {
            Salary += Salary * 10 / 100;
        }
    }
}

这个组件被命名为ReflectionIT.NDocSample。 同时，我把该组件生成的xml注释文件命名为ReflectionIT.NDocSample.XML 。请确认xml文件的名字和该组件的名字一致，否则IntelliSense将无法正确的工作。最后不要忘记编译该组件：编译之后就会生成这个xml文件。

第二步：使用NDoc创建 HTML Help 2 文档

在NDoc中同时包括GUI前台程序（NDocGUI.Exe）和 控制台文件（NDocConsole.exe）。我使用 NDocGUI来创建一个NDoc项目给我的NDocSample类库服务。您也可以通过“New From Visual Studio Solutioin…”菜单项来进行。

现在，你要将文档类型（Documentation Type）设置为“HtmlHelp2”。此外，还可以根据项目不同的情况来修改一些额外的属性，比如CopyrightHref, CopyrightText, HtmlHelpName 和Title等等。

（译注1：CopyrightHref中请使用 http://www.ncsi.com.cn这样的格式，而不要仅仅写成www.ncsi.com.cn）
（译注2：NDoc同时还可以支持生成其他类型的文档。如果您不需要把文档集成到VS.net里面，只是想生成一个MSDN风格的在线Web页或CHM文件的话，可以省略下面2步）

在NDoc生成Html Help 2文档之前，你需要安装Microsoft Html Workshop 和 Microsoft Visual Studio .NET Help Integration Kit (VSHIK2003)。（译注：如果没有安装这些程序就企图生成Html Help 2， NDoc会报错）最后生成的结果就是一个编译过的ReflectionIT.NDocSample.chm 文件（译注：以及一堆MSDN那样的*.HxC, *.HxF等文件）。

第三步：使用H2Reg注册帮助文档

我使用H2Reg来注册 NDocSample帮助文档。H2Reg.exe是一个很小的程序（177K），它能让你不使用MSI（Microsoft Installer）来注册MS Help 2.x 集：Namespaces, Titles, Plug-ins, 和 Filters。

要使用H2Ref，您必须创建一个ini文件来描述需要注册的对象。在下面就是我用来注册NDocSample所用的ini文件。

;------- Register -r switch

[Reg_Namespace]
;<nsName>|<nsColfile>|<nsDesc>
ReflectionIT.NDocSample|ReflectionIT.NDocSample.HxC|ReflectionIT NDocSample

[Reg_Title]
;<nsName>|<TitleID>|<LangId>|<HxS_HelpFile>|<HxI_IndexFile>|<HxQ_QueryFile>|
;<HxR_AttrQueryFile>|<HxsMediaLoc>|<HxqMediaLoc>|<HxrMediaLoc>|<SampleMediaLoc>
ReflectionIT.NDocSample|ReflectionIT.NDocSample|1033|ReflectionIT.NDocSample.HxS|||||||

;------- UnRegister -u switch

[UnReg_Namespace]
;<nsName>
ReflectionIT.NDocSample

[UnReg_Title]
;<nsName>|<TitleID>|<LangId>
ReflectionIT.NDocSample|ReflectionIT.NDocSample|1033

我把这个ini文件和刚才生成的ReflectionIT.NDocSample.HxC文件放到一个Help文件夹里面。在这个文件夹使用-R参数来运行H2Reg。 我也写了一个下面的这个Register.bat批处理文件来简化操作。

copy ..\Ndoc\doc\*.hxS
copy ..\Ndoc\doc\*.hxC
"C:\Program Files\Helpware\H2Reg\H2Reg.exe" -r cmdfile="C:\My Documents\Visual Studio Projects\NDocSample\Help\H2Reg_cmd.ini"

（译注：在h2reg的网站中提到注册过程中可能会出现一些问题。请参考这里：http://helpware.net/mshelp2/h2tutorial.htm#dtd）

第四步：把帮助文档集放入VSCC中

现在我们要作的最后一步就是把我们自己的帮助文档集成到Visual Studio .NET 2003 Combined Help Collection (VSCC)中。使用浏览器打开这个超连接：ms-help://MS.VSCC.2003/VSCCCommon/cm/CollectionManager.htm  在这个页面里钩选ReflectionIT.NDocSample 框，然后点击“Update VSCC“ 按钮。

你可以改变.HxC文件中HelpCollection节点Title属性值，来使用一个更具有描述性的名称。

结果

经过以上步骤之后，你就能看到NDoc生成的文件已经集成到了Visual Studio.Net开发环境中。 只要按F1，它就会出现在Dynamic Help窗口中。

结论：

通过使用C＃中的XML注释标签，以及NDoc和H2Reg，可以方便的对类库进行文档化，方便了项目中类库的使用和管理，也为类库重用打下了基础。