目录

• doc文件夹
  • 帮助文档
    • qdoc工具
    • doxygen工具
  • 配置文件
  • 
  • • • • qtcreator-project.qdocconf
        • qtcreator-developer.qdocconf

    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文档惊鸿一瞥：

    配置文件

    qtcreator编译时，会自动生成帮助文档。如果你安装了qt，可以在QtTargetPath¹\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
    ...

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

    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帮助手册的截图。

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

原文地址：https://www.cnblogs.com/uwiyrwiufsjc/p/12426467.html