終于到了激動(dòng)人心的時(shí)刻了。今天的博客內(nèi)容將永遠(yuǎn)消除Visual Studio的本地C++XML注釋編譯出來(lái)的XML文檔沒(méi)有辦法生成可讀文檔的根本原因。
首先介紹一下C++的XML注釋。在啟用注釋之前，我們必須先去工程屬性里面，把[C/C++ -> Output Files -> Generate Xml Documentation Files]設(shè)置成Yes。這樣我們就可以在C++的類啊函數(shù)上面寫XML注釋，然后被編譯成一份帶有符號(hào)鏈接的XML注釋集合。這里先給一個(gè)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;
};
這個(gè)XML注釋的格式是Visual Studio的統(tǒng)一格式。無(wú)論C++、C#和VB等語(yǔ)言都可以使用。在編譯之后會(huì)給出下面的一個(gè)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++編譯器幫我們把每一個(gè)XML注釋都標(biāo)注了一個(gè)符號(hào)鏈接的名字，也就是<member name="這里">。T:開(kāi)頭的是類型，M:開(kāi)頭的是函數(shù)，還有各種各樣的規(guī)則都寫在了MSDN里面，大家去查一下就知道了。我們首先回憶一下msdn的.net framework的文檔，文檔里面的每一個(gè)類的基類也好，每一個(gè)函數(shù)的參數(shù)類型和返回類型也好，都是超鏈接。為了生成這樣子的文檔，我們首先就要知道一個(gè)函數(shù)的參數(shù)類型和返回類型究竟是什么。但是在這里我們發(fā)現(xiàn)這份XML并不包含這個(gè)內(nèi)容。這也是為什么找不到一個(gè)生成本地C++XML注釋的可讀文檔工具的原因。而C++/CLI也好，.net的其他語(yǔ)言也好，都有這樣的工具，因?yàn)?net的可執(zhí)行文件可以反射出每一個(gè)符號(hào)的所有細(xì)節(jié)內(nèi)容。
這也就是為什么有
上一篇博客的原因。既然可執(zhí)行文件不包含元數(shù)據(jù)，那么pdb總包含的吧。良心的Visual Studio提供了我們msdia100.dll這個(gè)COM庫(kù)，使得我們可以做到從pdb讀取符號(hào)內(nèi)容的事情。當(dāng)然上一篇博客是針對(duì)VisualStudio本地C++編譯出來(lái)的pdb開(kāi)發(fā)的，不能適合所有種類的pdb。
有了這個(gè)pdb之后，我們把pdb用C++調(diào)用msdia100.dll先生成一份xml，然后就可以用偉大的.net linq to xml來(lái)完成接下來(lái)的事情了。現(xiàn)在我們手上有了兩份xml，一份是xml注釋，另一份是pdb符號(hào)表。利用
Vczh Library++ 3.0的[Tools\Release\SideProjects\GacUISrc\Xml2Doc\Xml2Doc.csproj]項(xiàng)目里面的代碼，就可以將這兩份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> 現(xiàn)在一個(gè)類型和函數(shù)的xml注釋也好，他的基類啊函數(shù)的參數(shù)類型返回類型也好，全部都出現(xiàn)了。下面可以做的事情就很多了。譬如說(shuō)自己寫一個(gè)xml到html文檔的轉(zhuǎn)換程序啦，或者用偉大的.net linq to xml把這個(gè)xml一轉(zhuǎn)成為其他xml格式，然后使用現(xiàn)有的工具生成文檔啦，所有的事情都可以做了。
我接下來(lái)會(huì)根據(jù)GacUI的情況不斷增加這個(gè)小工具的功能，最終讓他可以產(chǎn)生一份好的GacUI的文檔，不僅包含XML注釋的內(nèi)容，還可以包含外部插入的tutorial啊，帶高亮的code sample等等。
posted on 2012-03-09 17:04
陳梓瀚(vczh) 閱讀(6791)
評(píng)論(7) 編輯 收藏 引用 所屬分類:
C++ 、
GacUI