.NET文档生成工具2.2——扩展注释标志

ADB2.2支持自定义文档生成器，并提供了DocumentBuilder，CHMDocumentBuilderFactory和MSDNStyleCHMDocumentBuilder三个基类，通过继承这三个类，您可以方便的扩展出自己需要的文档生成器。下文将介绍如何编写文档生成器。
一、ADB的类图



二、MainForm（主界面）和文档生成器的交互
MainForm类负责读取程序集及其XML注释，文档生成器通过MainForm提供的IGetData接口获取程序集的成员（类型，方法，属性等），通过IInteract接口同用户交互（如显示进度等）。
三、编写文档生成器的三种方法
从ADB的类图可以看到，ADB提供了DocumentBuilder，CHMDocumentBuilderFactory和MSDNStyleCHMDocumentBuilder三个基类，继承这三个基类中的任何一个都可以扩展出文档生成器，根据继承基类的不同，可以有三种编写文档生成器的方法：

方法一：继承DocumentBuilder，DocumentBuilder是最基本的文档生成器基类，继承DocumentBuilder后，派生类可以通过IGetData获取程序集中所有类型及其成员的状态（是否选中）和对应XML注释，在生成过程中，可以通过IInteract接口同用户进行交互（如：报告进度）；

方法二：继承CHMDocumentBuilderFactory，CHMDocumentBuilderFactory有三个虚函数，其名称及说明如下

CreateNamespacePage	生成命名空间页面
CreateTypePage	生成类型（类，接口，结构，枚举或委托）页面
CreateMemberPage	生成类型成员（方法，属性，字段或事件）页面

CHMDocumentBuilderFactory的职责是将CreateNamespacePage，CreateTypePage和CreateMemberPage生成的页面编译为CHM文档，因此，当你想编写一个自定义风格样式（比如MSDN2008样式）的文档时，只需继承此类并重写CreateNamespacePage，CreateTypePage和CreateMemberPage三个方法即可，而不需要关心编译CHM的细节。

方法三：继承MSDNStyleCHMDocumentBuilder，MSDNStyleCHMDocumentBuilder继承于CHMDocumentBuilderFactory，并重写了CreateNamespacePage，CreateTypePage和CreateMemberPage以生成MSDN2005样式的文档页面，MSDNStyleCHMDocumentBuilder的GetTag方法为虚函数，如果要扩展注释标志，只需继承该类，并重写GetTag方法即可。

四、编写文档生成器示例
本文着重说明如何扩展注释标志(即方法三)，下面通过一个例子说明如何通过继承MSDNStyleCHMDocumentBuilder扩展注释标志：
1.目标
编写一个文档生成器，用于生成MSDN2005样式的CHM文档并扩展<image>标志，<image>标志用于在文档中插入图片，<image>的src属性用于指定图片的位置（相对于XML注释文件）。
2.实现方式
继承MSDNStyleCHMDocumentBuilder并重写GetTag方法。
3.实现步骤
工程文件
(1)新建一个.net类库工程（名称为DemoCustomBuilder）；
(2)引用ADB.Factories.dll（可在ADB目录下找到该文件）；
(3)创建文档生成器配置文件，创建一个名为DemoCustomBuilder.builder文件（保存为UTF-8格式），放置在DemoCustomBuilder.dll所在的目录下，DemoCustomBuilder.builder内容如下:
<?xml version="1.0" encoding="utf-8"?>
<!--
注意：
1.CustomBuilder必须有Name和Entry两个属性(区分大小写),同一程序集内可以有多个文档生成器；
2.Entry必须使用类的完全限定名（命名空间.类名）；
3.<?xml version="1.0" encoding="utf-8"?>指定的编码必须和文件保存的编码一致。
4.该配置文件的名称必须和包含生成器的程序集的名称一样（例如：程序集的名称为CustomBuilder.dll则配置文件应该命名为CustomBuilder.builder）
-->
<Builders ADBVersion="2.2.0.0">
<CustomBuilder Name="示例文档生成器" Entry="ADB.DemoCustomBuilder"/>
</Builders>
(4) 调试配置:
打开DemoCustomBuilder的属性页，设置调试启动项：



(5)添加一个名称为DemoCustomBuilder的类
using System;
using System.Collections.Generic;
using System.Text;
using ADB.Factories;
using Microsoft.VisualBasic.FileIO;

namespace ADB
{
/// <summary>
/// 示例文档生成器，支持<image>标志
/// </summary>
public class DemoCustomBuilder : ADB.Factories.MSDNStyleCHMDocumentBuilder
{
public DemoCustomBuilder(IGetData data, IInteract interact)
: base(data, interact)
{
}

protected override string GetTag(System.Xml.XmlElement elem, string xmlFile)
{
switch (elem.Name)
{
case "image":
{
StringBuilder tag = new StringBuilder();
string src = elem.GetAttribute("src");
if (!string.IsNullOrEmpty(src))
{
try
{
//将图片拷贝到生成页面的目录中（通过属性HtmlFileDirectory获取保存页面的目录）
FileSystem.CopyFile(xmlFile + """" + src, HtmlFileDirectory + """" + src, true);
}
finally
{
}
//生成HTML标志
tag.AppendFormat("<img src='{0}'/>", src);
}
return tag.ToString();
}
default:
{
//其它标志由基类处理
return base.GetTag(elem, xmlFile);
}
}
}
}
}
生成工程，一个支持image标志的文档生成器就完成了。
(6)测试：
用于测试的类:
using System;
using System.Collections.Generic;
using System.Text;

namespace TestClassLibrary
{
/// <summary>
/// 测试
/// </summary>
public class TestClass
{
/// <summary>
/// Method
/// </summary>
/// <remarks><image src="Images"1.jpg"/></remarks>
public void Method()
{
}
}
}
生成的文档:



(7)让ADB自动加载自定义的文档生成器
在ADB目录下的builders文件夹中新建一个目录，将包含有文档生成器的程序集，引用的程序集和配置文件拷贝到该新建的目录中即可。（程序集和配置文件名称必须相同，配置文件的扩展名为.builder）。
工程文件