doc文件夹

doc文件夹

对于bin和dist文件夹这里就不做过多的介绍了。我们首先来重点关注doc文件夹。对于理解源码，帮助文档总是能起到非常有效的作用。

帮助文档

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

源代码中的注释
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怎么使用，这里就不再展开了，请自行查阅相关资料。

doxygen工具

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

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

扫描二维码关注公众号，回复： 9066911 查看本文章

想必大家都明白了吧，他们采用的就是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文档惊鸿一瞥：

qtcreator.qdocconf

首先在doc目录下，使用qtcreator.qdocconf配置文件编译html文档。命令如下：

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

doc\config目录下有一些qdocconf中使用了$Var环境变量，如QTC_VERSION，如果没有设置，可能会报错，手动改了即可。

生成的文档，和我们qt creator IDE中帮助的内容是一样的，可以在QtTargetPath\Docs\Qt-5.11.1下找到，这里就不再多展开了。

qtcreator-dev.qdocconf

我们再关注下doc\api目录，里面有coding-style和plugin等相关文档，对于我们理解源码很有帮助，我们也进行生成。

进入doc\api目录，直接使用下面命令编译。

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

我这里报错缺少依赖项目。因此进行了如下修改：

拷贝doc\config\qtcreator-developer.qdocconf到doc\api目录下，改名为zx.qdocconf。
修改zx.qdocconf文件。
- 删除headerdirs和sourcedirs中无关的内容。
  headerdirs = .
  sourcedirs = .
- 改变include文件路径。
  
  include(../config/macros.qdocconf)
  include(../config/qt-cpp-ignore.qdocconf)
  include(../config/qt-defines.qdocconf)
- 修改$Var。如QTC_VERSION为4.6.2等。
修改qtcreator-dev.qdocconf。

include(../config/qtcreator-developer.qdocconf)改为include(zx.qdocconf)。
使用上述命令再次编译即可。

最终结果示例如下：

下面我们对生成的帮助文档进行学习。

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