合并Visual Studio本地C++XML注释文档和PDB的符号内容
终于到了激动人心的时刻了。今天的博客内容将永远消除Visual Studio的本地C++XML注释编译出来的XML文档没有办法生成可读文档的根本原因。
首先介绍一下C++的XML注释。在启用注释之前，我们必须先去工程属性里面，把[C/C++ -> Output Files -> Generate Xml Documentation Files]设置成Yes。这样我们就可以在C++的类啊函数上面写XML注释，然后被编译成一份带有符号链接的XML注释集合。这里先给一个GacUI的XML注释的例子： /// <summary>
/// This is the interface for graphics renderers.
/// </summary>
class IGuiGraphicsRenderer : public Interface
{
public:
/// <summary>
/// Access the graphics <see cref="IGuiGraphicsRendererFactory"></see> that is used to create this graphics renderer.
/// </summary>
/// <returns>Returns the related factory.</returns>
virtual IGuiGraphicsRendererFactory* GetFactory()=0;
/// <summary>
/// Initialize the grpahics renderer by binding a <see cref="IGuiGraphicsElement"></see> to it.
/// </summary>
/// <param name="element">The graphics element to bind.</param>
virtual void Initialize(IGuiGraphicsElement* element)=0;
/// <summary>
/// Release all resources that used by this renderer.
/// </summary>
virtual void Finalize()=0;
/// <summary>
/// Set a <see cref="IGuiGraphicsRenderTarget"></see> to this element.
/// </summary>
/// <param name="renderTarget">The graphics render target. It can be NULL.</param>
virtual void SetRenderTarget(IGuiGraphicsRenderTarget* renderTarget)=0;
/// <summary>
/// Render the graphics element using a specified bounds.
/// </summary>
/// <param name="bounds">Bounds to decide the size and position of the binded graphics element.</param>
virtual void Render(Rect bounds)=0;
/// <summary>
/// Notify that the state in the binded graphics element is changed. This function is usually called by the element itself.
/// </summary>
virtual void OnElementStateChanged()=0;
/// <summary>
/// Calculate the minimum size using the binded graphics element and its state.
/// </summary>
/// <returns>The minimum size.</returns>
virtual Size GetMinSize()=0;
};
这个XML注释的格式是Visual Studio的统一格式。无论C++、C#和VB等语言都可以使用。在编译之后会给出下面的一个XML文件： <?xml version="1.0"?>
<doc>
<assembly>
"GacUISrc"
</assembly>
<members>
<member name="M:vl.presentation.elements.IGuiGraphicsRenderer.GetMinSize">
<summary>
Calculate the minimum size using the binded graphics element and its state.
</summary>
<returns>The minimum size.</returns>
</member>
<member name="M:vl.presentation.elements.IGuiGraphicsRenderer.OnElementStateChanged">
<summary>
Notify that the state in the binded graphics element is changed. This function is usually called by the element itself.
</summary>
</member>
<member name="M:vl.presentation.elements.IGuiGraphicsRenderer.Render(vl.presentation.Rect)">
<summary>
Render the graphics element using a specified bounds.
</summary>
<param name="bounds">Bounds to decide the size and position of the binded graphics element.</param>
</member>
<member name="M:vl.presentation.elements.IGuiGraphicsRenderer.SetRenderTarget(vl.presentation.elements.IGuiGraphicsRenderTarget*)">
<summary>
Set a <see cref="T:vl.presentation.elements.IGuiGraphicsRenderTarget" /> to this element.
</summary>
<param name="renderTarget">The graphics render target. It can be NULL.</param>
</member>
<member name="M:vl.presentation.elements.IGuiGraphicsRenderer.Finalize">
<summary>
Release all resources that used by this renderer.
</summary>
</member>
<member name="M:vl.presentation.elements.IGuiGraphicsRenderer.Initialize(vl.presentation.elements.IGuiGraphicsElement*)">
<summary>
Initialize the grpahics renderer by binding a <see cref="T:vl.presentation.elements.IGuiGraphicsElement" /> to it.
</summary>
<param name="element">The graphics element to bind.</param>
</member>
<member name="M:vl.presentation.elements.IGuiGraphicsRenderer.GetFactory">
<summary>
Access the graphics <see cref="T:vl.presentation.elements.IGuiGraphicsRendererFactory" /> that is used to create this graphics renderer.
</summary>
<returns>Returns the related factory.</returns>
</member>
<member name="T:vl.presentation.elements.IGuiGraphicsRenderer">
<summary>
This is the interface for graphics renderers.
</summary>
</member>
</members>
</doc>
我们可以看出，C++编译器帮我们把每一个XML注释都标注了一个符号链接的名字，也就是<member name="这里">。T:开头的是类型，M:开头的是函数，还有各种各样的规则都写在了MSDN里面，大家去查一下就知道了。我们首先回忆一下msdn的.net framework的文档，文档里面的每一个类的基类也好，每一个函数的参数类型和返回类型也好，都是超链接。为了生成这样子的文档，我们首先就要知道一个函数的参数类型和返回类型究竟是什么。但是在这里我们发现这份XML并不包含这个内容。这也是为什么找不到一个生成本地C++XML注释的可读文档工具的原因。而C++/CLI也好，.net的其他语言也好，都有这样的工具，因为.net的可执行文件可以反射出每一个符号的所有细节内容。
这也就是为什么有上一篇博客http://www.2cto.com/kf/201203/122574.html
有了这个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 version="1.0" encoding="utf-8"?>
<cppdoc>
<namespace name="">
<namespace name="vl">
<namespace name="presentation">
<namespace name="elements">
<type name="IGuiGraphicsRenderer" fullName="vl::presentation::elements::IGuiGraphicsRenderer">
<document>
<member name="T:vl.presentation.elements.IGuiGraphicsRenderer">
<summary>
This is the interface for graphics renderers.
</summary>
</member>
</document>
<functionGroup name="GetMinSize">
<function name="GetMinSize" fullName="GetMinSize" isStatic="true" access="Public" kind="Abstract">
<returnType>vl::presentation::Size</returnType>
<document>
<member name="M:vl.presentation.elements.IGuiGraphicsRenderer.GetMinSize">
<summary>
Calculate the minimum size using the binded graphics element and its state.
</summary>
<returns>The minimum size.</returns>
</member>
</document>
</function>
</functionGroup>
<functionGroup name="OnElementStateChanged">
<function name="OnElementStateChanged" fullName="OnElementStateChanged" isStatic="true" access="Public" kind="Abstract">
<returnType>void</returnType>
<document>
<member name="M:vl.presentation.elements.IGuiGraphicsRenderer.OnElementStateChanged">
<summary>
Notify that the state in the binded graphics element is changed. This function is usually called by the element itself.
</summary>
</member>
</document>
</function>
</functionGroup>
<functionGroup name="Render">
<function name="Render" fullName="Render" isStatic="true" access="Public" kind="Abstract">
<returnType>void</returnType>
<parameterType>vl::presentation::Rect</parameterType>
<document>
<member name="M:vl.presentation.elements.IGuiGraphicsRenderer.Render(vl.presentation.Rect)">
<summary>
Render the graphics element using a specified bounds.
</summary>
<param name="bounds">Bounds to decide the size and position of the binded graphics element.</param>
</member>
</document>
</function>
</functionGroup>
<functionGroup name="SetRenderTarget">
<function name="SetRenderTarget" fullName="SetRenderTarget" isStatic="true" access="Public" kind="Abstract">
<returnType>void</returnType>
<parameterType>vl::presentation::elements::IGuiGraphicsRenderTarget*</parameterType>
<document>
<member name="M:vl.presentation.elements.IGuiGraphicsRenderer.SetRenderTarget(vl.presentation.elements.IGuiGraphicsRenderTarget*)">
<summary>
Set a <see cref="T:vl.presentation.elements.IGuiGraphicsRenderTarget" /> to this element.
</summary>
<param name="renderTarget">The graphics render target. It can be NULL.</param>
</member>
</document>
</function>
</functionGroup>
<functionGroup name="Finalize">
<function name="Finalize" fullName="Finalize" isStatic="true" access="Public" kind="Abstract">
<returnType>void</returnType>
<document>
<member name="M:vl.presentation.elements.IGuiGraphicsRenderer.Finalize">
<summary>
Release all resources that used by this renderer.
</summary>
</member>
</document>
</function>
</functionGroup>
<functionGroup name="Initialize">
<function name="Initialize" fullName="Initialize" isStatic="true" access="Public" kind="Abstract">
<returnType>void</returnType>
<parameterType>vl::presentation::elements::IGuiGraphicsElement*</parameterType>
<document>
<member name="M:vl.presentation.elements.IGuiGraphicsRenderer.Initialize(vl.presentation.elements.IGuiGraphicsElement*)">
<summary>
Initialize the grpahics renderer by binding a <see cref="T:vl.presentation.elements.IGuiGraphicsElement" /> to it.
</summary>
<param name="element">The graphics element to bind.</param>
</member>
</document>
</function>
</functionGroup>
<functionGroup name="GetFactory">
<function name="GetFactory" fullName="GetFactory" isStatic="true" access="Public" kind="Abstract">
<returnType>vl::presentation::elements::IGuiGraphicsRendererFactory*</returnType>
<document>
<member name="M:vl.presentation.elements.IGuiGraphicsRenderer.GetFactory">
<summary>
Access the graphics <see cref="T:vl.presentation.elements.IGuiGraphicsRendererFactory" /> that is used to create this graphics renderer.
</summary>
<returns>Returns the related factory.</returns>
</member>
</document>
</function>
</functionGroup>
</type>
</namespace>
</namespace>
</namespace>
</namespace>
</cppdoc>
现在一个类型和函数的xml注释也好，他的基类啊函数的参数类型返回类型也好，全部都出现了。下面可以做的事情就很多了。譬如说自己写一个xml到html文档的转换程序啦，或者用伟大的.net linq to xml把这个xml一转成为其他xml格式，然后使用现有的工具生成文档啦，所有的事情都可以做了。
我接下来会根据GacUI的情况不断增加这个小工具的功能，最终让他可以产生一份好的GacUI的文档，不仅包含XML注释的内容，还可以包含外部插入的tutorial啊，带高亮的code sample等等。
摘自 λ-calculus（惊愕到手了欧耶）
