终于到了激动人心的时刻了。今天的博客内容将永远消除Visual Studio的本地C++XML注释编译出来的XML文档没有办法生成可读文档的根本原因。

    首先介绍一下C++的XML注释。在启用注释之前，我们必须先去工程属性里面，把[C/C++ -> Output Files -> Generate Xml Documentation Files]设置成Yes。这样我们就可以在C++的类啊函数上面写XML注释，然后被编译成一份带有符号链接的XML注释集合。这里先给一个GacUI的XML注释的例子：
    这个XML注释的格式是Visual Studio的统一格式。无论C++、C#和VB等语言都可以使用。在编译之后会给出下面的一个XML文件：
    我们可以看出，C++编译器帮我们把每一个XML注释都标注了一个符号链接的名字，也就是<member name="这里">。T:开头的是类型，M:开头的是函数，还有各种各样的规则都写在了MSDN里面，大家去查一下就知道了。我们首先回忆一下msdn的.net framework的文档，文档里面的每一个类的基类也好，每一个函数的参数类型和返回类型也好，都是超链接。为了生成这样子的文档，我们首先就要知道一个函数的参数类型和返回类型究竟是什么。但是在这里我们发现这份XML并不包含这个内容。这也是为什么找不到一个生成本地C++XML注释的可读文档工具的原因。而C++/CLI也好，.net的其他语言也好，都有这样的工具，因为.net的可执行文件可以反射出每一个符号的所有细节内容。

    这也就是为什么有上一篇博客的原因。既然可执行文件不包含元数据，那么pdb总包含的吧。良心的Visual Studio提供了我们msdia100.dll这个COM库，使得我们可以做到从pdb读取符号内容的事情。当然上一篇博客是针对VisualStudio本地C++编译出来的pdb开发的，不能适合所有种类的pdb。

    有了这个pdb之后，我们把pdb用C++调用msdia100.dll先生成一份xml，然后就可以用伟大的.net linq to xml来完成接下来的事情了。现在我们手上有了两份xml，一份是xml注释，另一份是pdb符号表。利用Vczh Library++ 3.0的[Tools\Release\SideProjects\GacUISrc\Xml2Doc\Xml2Doc.csproj]项目里面的代码，就可以将这两份xml合并成第三份xml了：
    现在一个类型和函数的xml注释也好，他的基类啊函数的参数类型返回类型也好，全部都出现了。下面可以做的事情就很多了。譬如说自己写一个xml到html文档的转换程序啦，或者用伟大的.net linq to xml把这个xml一转成为其他xml格式，然后使用现有的工具生成文档啦，所有的事情都可以做了。

    我接下来会根据GacUI的情况不断增加这个小工具的功能，最终让他可以产生一份好的GacUI的文档，不仅包含XML注释的内容，还可以包含外部插入的tutorial啊，带高亮的code sample等等。