終於到了激動人心的時刻了。今天的博客內容將永遠消除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.BkJia.com/kf/201203/122574.html 的原因。既然可執行文件不包含元數據，那麼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 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等等。
