qt creator源码全方面分析(2)

02/06 14:28
阅读数 48

[TOC]

doc文件夹

对于bin和dist文件夹这里就不做过多的介绍了。我们首先来重点关注doc文件夹。对于理解源码,帮助文档总是能起到非常有效的作用。其实,我们在第一章《目录介绍》中已经对doc文件夹进行了一个大概的介绍。

帮助文档

帮助文档的来源有两个组成部分:

  1. 源代码中的注释

  2. qdoc文件

两者都采用一定约束规范的编写形式,来添加注释和说明信息。示例如下:

/*!
    \class XXX
    \brief The brief description of the class XXX
    \details The details description of the clss XXX
*/

qdoc工具

qt使用qdoc.exe软件来制作帮助文档。软件需要qdocconf配置文件,该文件描述了文档来源和相关配置参数等。

对于qdoc.exe怎么使用,这里就不再展开了,请自行查阅相关资料。示例如下:

...\bin\qdoc.exe --outputdir ./my-html-doc-qtcreator qtcreator.qdocconf

doxygen工具

这里我们讨论一下doc\doxygen文件夹,里面只有一个Doxyfile文件

这是文件夹干什么用的呢?不知道大家日常看大牛的开源代码时,是否时常感叹为什么别人的代码写的那么的优雅,大段大段的注释那么有结构,官方帮助文档那么的清晰完整!!

想必大家都明白了吧,他们采用的就是doxygen工具,该工具从相关的代码源文件中生成文档,包括html,pdf,unix man page等。只要你按照doxygen的代码注释规范来编写注释,即可使用该工具生成文档。

这里doxyfile的作用和qdocconf是一样的,就是配置文件。具体内容请参考官网

它支持qt,java等多种风格,qt风格如下,这跟qdoc中使用的差不了多少:

//!  A test class. 
/*!
  A more elaborate class description.
*/
class QTstyle_Test
{
  public:
    //! An enum.
    /*! More detailed enum description. */
    enum TEnum { 
                 TVal1, /*!< Enum value TVal1. */  
                 TVal2, /*!< Enum value TVal2. */  
                 TVal3  /*!< Enum value TVal3. */  
               } 
         //! Enum pointer.
         /*! Details. */
         *enumPtr, 
         //! Enum variable.
         /*! Details. */
         enumVar;  
    
    //! A constructor.
    /*!
      A more elaborate description of the constructor.
    */
    QTstyle_Test();
 
    //! A destructor.
    /*!
      A more elaborate description of the destructor.
    */
   ~QTstyle_Test();
    
    //! A normal member taking two arguments and returning an integer value.
    /*!
      \param a an integer argument.
      \param s a constant character pointer.
      \return The test results
      \sa QTstyle_Test(), ~QTstyle_Test(), testMeToo() and publicVar()
    */
    int testMe(int a,const char *s);
       
    //! A pure virtual member.
    /*!
      \sa testMe()
      \param c1 the first argument.
      \param c2 the second argument.
    */
    virtual void testMeToo(char c1,char c2) = 0;
   
    //! A public variable.
    /*!
      Details.
    */
    int publicVar;
       
    //! A function variable.
    /*!
      Details.
    */
    int (*handler)(int a,int b);
};

生成的html文档惊鸿一瞥:

<img src="https://img2018.cnblogs.com/blog/1921368/202002/1921368-20200226204234978-1809301601.png" alt="image-20200204164006773" style="zoom:50%;" />

配置文件

qtcreator编译时,会自动生成帮助文档。如果你安装了qt,可以在QtTargetPath[^1]\Tools\QtCreator\share\doc\qtcreator文件夹下发现这些帮助文档。

doc文件夹中最核心的两个配置文件为config子文件夹下的qtcreator-project.qdocconf和qtcreator-developer.qdocconf。

qtcreator-project.qdocconf

该配置文件生成的html帮助手册,用于介绍qtcreator软件如何使用的。我们可以在qtcreator软件的帮助模式中看到的。html文件在上述安装路径的qtcreator子文件夹中。

qtcreator-project.qdocconf具体如下:

# 设置源路径
headerdirs =
sourcedirs = ../src
imagedirs = ../images \
            ...
...
# 包含通用配置
include(macros.qdocconf)
include(qt-cpp-ignore.qdocconf)
include(qt-defines.qdocconf)

# 过滤文件尾缀
sources.fileextensions         = "*.qdoc"

# 设置属性
qhp.projects            = QtCreator
qhp.QtCreator.file             = qtcreator.qhp
qhp.QtCreator.namespace        = org.qt-project.qtcreator.$QTC_VERSION_TAG
qhp.QtCreator.virtualFolder    = doc
# 标题
qhp.QtCreator.indexTitle       = Qt Creator Manual $QTC_VERSION
...

下面是软件帮助模式的截图。

<img src="https://img2018.cnblogs.com/blog/1921368/202002/1921368-20200225210443018-1913526664.png" alt="image-20200225205008397" style="zoom:33%;" />

qtcreator-developer.qdocconf

该配置文件生成的html帮助手册,用于介绍如何扩展qtcreator软件的功能,以及扩展会用到的相关类。html文件在上述安装路径的qtcreator-dev子文件夹中。

qtcreator-dev.qdocconf具体如下:

# 设置源路径
headerdirs              = . \
                          ../api \
                          ../../src/libs/aggregation \
                          ...

sourcedirs              = . \
                          ../api \
                          ../../src/libs/aggregation \
                          ...
...
# 过滤文件尾缀
headers.fileextensions  = "*.h"
sources.fileextensions  = "*.cpp *.qdoc"
...
# 包含通用配置
include(macros.qdocconf)
include(qt-cpp-ignore.qdocconf)
include(qt-defines.qdocconf)

# 设置属性
qhp.projects            = QtCreatorDev
qhp.QtCreatorDev.file             = qtcreator-dev.qhp
qhp.QtCreatorDev.namespace        = org.qt-project.qtcreator.developer.$QTC_VERSION_TAG
qhp.QtCreatorDev.virtualFolder    = doc
# 标题
qhp.QtCreatorDev.indexTitle       = Extending Qt Creator Manual
...

下面是html帮助手册的截图。

<img src="https://img2018.cnblogs.com/blog/1921368/202002/1921368-20200225210512305-744785931.png" alt="image-20200225205008397" style="zoom:33%;" />

下面开始,我们对生成的Extending Qt Creator Manual帮助文档进行学习。

[^1]:QtTargetPath为Qt的安装目录,不是qt creator。


原创造福大家,共享改变世界

献出一片爱心,温暖作者心灵

<img src="https://img2018.cnblogs.com/blog/1921368/202002/1921368-20200223073938417-815334096.jpg" style="zoom: 50%;" />


原文出处:https://www.cnblogs.com/codeForFamily/p/qt-creator-ide-source-learn-2.html

展开阅读全文
打赏
0
0 收藏
分享
加载中
更多评论
打赏
0 评论
0 收藏
0
分享
返回顶部
顶部