随笔-341  评论-2670  文章-0  trackbacks-0
    终于到了激动人心的时刻了。今天的博客内容将永远消除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的可执行文件可以反射出每一个符号的所有细节内容。

    这也就是为什么有上一篇博客的原因。既然可执行文件不包含元数据,那么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-09 17:04 陈梓瀚(vczh) 阅读(6585) 评论(7)  编辑 收藏 引用 所属分类: C++GacUI

评论:
# re: 合并Visual Studio本地C++XML注释文档和PDB的符号内容 2012-03-09 18:09 | ArthasLee
果然是GaCGUI的作者,尼桑跟我深感安慰阿鲁~  回复  更多评论
  
# re: 合并Visual Studio本地C++XML注释文档和PDB的符号内容 2012-03-10 00:27 | 空明流转
你做个EXE吧。  回复  更多评论
  
# re: 合并Visual Studio本地C++XML注释文档和PDB的符号内容 2012-03-10 01:09 | 布拉德比特
窃以为还是doxygen比较爽....  回复  更多评论
  
# re: 合并Visual Studio本地C++XML注释文档和PDB的符号内容 2012-03-10 02:00 | 陈梓瀚(vczh)
@空明流转
exe已经有了。  回复  更多评论
  
# re: 合并Visual Studio本地C++XML注释文档和PDB的符号内容 2012-03-10 22:56 | tb
牛人啊   回复  更多评论
  
# re: 合并Visual Studio本地C++XML注释文档和PDB的符号内容 2012-03-12 04:42 | 装配脑袋
感觉你做的越来越多,但离一个普通用户能够容易使用的亲切状态越来越远了。。  回复  更多评论
  
# re: 合并Visual Studio本地C++XML注释文档和PDB的符号内容 2012-03-12 09:48 | 陈梓瀚(vczh)
@装配脑袋
这个纯粹是类似于source depot的tools目录下面的程序,用户是不需要管的,啊哈哈哈哈,他们只要用preprocess过的东西就行了。  回复  更多评论
  

只有注册用户登录后才能发表评论。
【推荐】超50万行VC++源码: 大型组态工控、电力仿真CAD与GIS源码库
网站导航: 博客园   IT新闻   BlogJava   知识库   博问   管理