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

 

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

 

By: Fons Sonnemans

编译：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）

Here are some typical registration problems. Currently there are no known problems with H2Reg.exe itself.

1.     Registration works on the development machines only. Plug-in fails on customer machines.

Collection level .Hx? files must not contain reference to a DTD file.
The customer wont have VSHIK installed and thus wont have the DTD files.

2.     Registration fails due to VStudio MSI problems.

Registration problems often happen not because of the Registration system but because Visual Studio MSI Installation has corrupted the MS.VSCC namespace or the MS Help 2 runtime installation.

The solution here is to ask the customer to Repair the VStudio installation by using the VStudio Setup disks. Sometimes this involves a complete uninstall and reinstall.

 

 

第四步：把帮助文档集放入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，可以方便的对类库进行文档化，方便了项目中类库的使用和管理，也为类库重用打下了基础。