合併Visual Studio本地C++XML註釋文件和PDB的符號內容
阿新 • • 發佈：2018-12-27
終於到了激動人心的時刻了。今天的部落格內容將永遠消除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:
///<summary>/// Access the graphics <see cref="IGuiGraphicsRendererFactory"></see> that is used to create this graphics renderer.
///</summary>///<returns>Returns the related factory.</returns>virtual
///<summary>/// Initialize the grpahics renderer by binding a <see cref="IGuiGraphicsElement"></see> to it.
///</summary>///<param name="element">The graphics element to bind.</param>virtualvoid Initialize(IGuiGraphicsElement
///<summary>/// Release all resources that used by this renderer.
///</summary>virtualvoid 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>virtualvoid 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>virtualvoid 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>virtualvoid 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的可執行檔案可以反射出每一個符號的所有細節內容。
這也就是為什麼有上一篇部落格的原因。既然可執行檔案不包含元資料，那麼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等等。 posted on 2012-03-10 09:04 陳梓瀚(vczh) 閱讀(6188) 評論(7) 編輯 收藏 引用 所屬分類: C++ 、GacUI
首先介紹一下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:
///<summary>/// Access the graphics <see cref="IGuiGraphicsRendererFactory"></see> that is used to create this graphics renderer.
///</summary>///<returns>Returns the related factory.</returns>virtual
///<summary>/// Initialize the grpahics renderer by binding a <see cref="IGuiGraphicsElement"></see> to it.
///</summary>///<param name="element">The graphics element to bind.</param>virtualvoid Initialize(IGuiGraphicsElement
///<summary>/// Release all resources that used by this renderer.
///</summary>virtualvoid 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>virtualvoid 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>virtualvoid 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>virtualvoid 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的可執行檔案可以反射出每一個符號的所有細節內容。
這也就是為什麼有上一篇部落格的原因。既然可執行檔案不包含元資料，那麼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等等。 posted on 2012-03-10 09:04 陳梓瀚(vczh) 閱讀(6188) 評論(7) 編輯 收藏 引用 所屬分類: C++ 、GacUI