在Qt示例项目的C ++ / QML源中的//！ [0]的含义是什么？

例如：  //！ [0] 

GLWidget :: GLWidget（Helper * helper，QWidget * parent） ：QGLWidget（QGLFormat（QGL :: SampleBuffers），parent），helper（helper）  {
    elapsed = 0;  setFixedSize（840，400）;  setAutoFillBackground（false）; }  //！ [0]  //！ [1]  void GLWidget :: animate（）  {
    elapsed =（elapsed + qobject_cast< QTimer *>（sender（）） - > interval  repaint（）; }  //！ [1]  //！ [2]  void GLWidget :: paintEvent（QPaintEvent * event）  {
    QPainter painter;  painter.begin（this）;  painter.setRenderHint（QPainter :: Antialiasing）;  helper-> paint（& painter，event，elapsed）;  painter.end（）; }  //！ [2]

解决方案

 qdoc 语法

 

 

一、介绍什么是qdoc

Qdoc是开发者用于在软件工程中生成文档的一个工具。它从工程的源文件中提取qdoc类型注释，并以html页面或者DITA XML文档的形式格式化到文件中。Qdoc在.cpp和.qdoc文件中查找注释，而不会在.h文件中查找。一条qdoc注释往往以一个前置声明符号（!）开始。

二、使用qdoc的好处和缺点

优点：

a) 通过qdoc自动提取注释生成开发文档。

b) 在对外接口中可直接通过qdoc生成文档做接口文件，不用单独再写文档。

c) 将代码逻辑写到注释中，便于修改代码时修改。避免了之前单独出代码文档时修改代码忘记更新文档，造成文档代码不一致。

d) 支持多种格式输出，qch，html等格式，便于不同阅读方式。

缺点：

a)         必须按照qdoc的格式编写注释，并且注释必须与代码一致。

b)         Qdoc不能生成对私有函数注释输出（可通过修改源代码输出）。

c)         使用人数较少，网上文档较少，一般只能看官方文档。

三、创建Qdoc工程

1、 创建qoc的工程

添加空的qt工程，只需要pro文件，用于管理生成qch。

#-------------------------------------------------## Project created by QtCreator 2016-12-23 T15:22:06# 备注： 对整个工程生成qch文件#------------------------------------------------- #创建一个Makefile，不构建任何东西。TEMPLATE = aux include(doc.pri) # 生成qch文件需要添加此行PRE_TARGETDEPS += qch_docs

说明

TEMPLATE = aux：用于设置当前工程不调用编译器来创建目标，仅使用makefile生成器。

PRE_TARGETDEPS += qch_docs：设置当前工程依赖qch_docs

2、添加qdoc的目录结构

Qdoc工程目录结构仿照官方qdoc目录进行生成.如图1.

 

 

图1

config:存放doc工程的配置文件，很重要。Qdoc的基础配置文件必须放到此目录下，否则会导致生成的qch文件中一堆的没用的链接。如图2。Image文件夹和style文件夹存放一些引用的图片和html样式。后面会用到。

 

图2

global:全局的配置文件，存放全局qdocconf文件，如一些格式的，源文件编码，生成文档编码，宏定义，源文件后缀配置等。这里面会有一个template目录，用于存放 引用的图片和html样式。可到qt源码下拷贝过来。如图3。

 

图3

html:生成的html文件目录，qmake以后生成html文件。通过浏览器可直接打开查看文档。如图4。

 

图4

Images :图片文件路径，文档中可引入图片，所以此目录存放图片。

Src：很重要，用于添加自定义的一些qdoc文件，用于生成doc中的模块文档，对某个模块的单独说明可添加独立的qdoc文件，进行详细描述，不用添加到代码中。此目录文件在qmake的时候会遍历每个qdoc文件进行添加。Index.qdoc很重要，用于添加主页的信息的。如图5.

 

图5

pri文件在3中介绍。

3、添加qdoc的必须配置文件

①   pri文件：用于添加各种设置，如qdoc的输出路径，执行命令等。可参看assistant中qmake Manual章节。

 

#include($$_PRO_FILE_PWD_/target.pri)TargetName=doc HELPGENERATOR = $$shell_path($$[QT_INSTALL_BINS]/qhelpgenerator) #-platform minimalQDOC_BIN = $$shell_path($$[QT_INSTALL_BINS]/qdoc)QDOC_PREPARE = $$QDOC_BIN -prepareQDOC_GENERATE = $$QDOC_BIN -generateQDOC_GLOBAL = QT_INSTALL_DOCS=$$[QT_INSTALL_DOCS]/srcQDOC_INDEX_DIR=$$[QT_INSTALL_DOCS]#COMPAT = defineReplace(cmdEnv) {    !equals(QMAKE_DIR_SEP, /): 1 ~= s,^(.*)$,(set \\1) &&,g    return("$$1")}  defineReplace(qdoc) {    return("$$cmdEnv(SRCDIR=$$_PRO_FILE_PWD_../ OUTDIR=$$1 $$QDOC_GLOBAL) $$QDOC_BIN")} PROJECT_PWD=$$PWD/../message($$PROJECT_PWD) QHP_FILE = $$PROJECT_PWD/doc/html/$${TargetName}.qhpQCH_FILE = $$PROJECT_PWD/$${TargetName}.qch  doc_generate.TARGET = $$TargetName.qhpdoc_generate.commands = $$QDOC_PREPARE $$PWD/config/$${TargetName}.qdocconf -outputdir $$PROJECT_PWD/doc/html \    $$escape_expand(\n\t) $$QDOC_GENERATE $$PWD/config/$${TargetName}.qdocconf -outputdir $$PROJECT_PWD/doc/html qch_docs.TARGET=$$TargetName.qchqch_docs.commands = $$HELPGENERATOR -o $$QCH_FILE $$QHP_FILEqch_docs.depends += doc_generate QMAKE_EXTRA_TARGETS += doc_generate qch_docs win32 {    system(copy /y $$QCH_FILE $$PROJECT_PWD/)}

② qdocconf文件：为了生成文档，QDoc使用带有qdocconf扩展名的配置文件来存储配置设置.主要配置项目名称，输入输出路径，宏，版本号等信息。config目录下的doc.qdocconf.主要是针对当前工程进行设置的，global下的主要是通用的。

#自定义conf文件， 这里使用的是Qt提供的。include(../global/qt-module-defaults-offline.qdocconf)#此文件里面写了编码的格式，所以需要修改此里面的编码才有效include(../global/fileextensions.qdocconf)#此文件配置输出的html格式include(../global/qt-html-templates-offline.qdocconf) #项目#project                 = doc#项目名称description             = doc项目#版本号version                 = 1.0 #Qt 版本号， 可以定义自己的版本号，这是是为了使用以下Qt提供的conf文件QT_VER=1.0 #所依赖的模块depends += \    qtcore \    qtnetwork \    qtwidgets \    qmake \    xml #头文件路径headerdirs  +=.. \              ../src \              ../../doc \  #源代码路径sourcedirs  = .. \                ../src \                ../../doc \ outputformats=HTML #工程整体信息， 包括文件名、工程名、注册时的名称空间qhp.projects                 = docqhp.doc.file                 = doc.qhpqhp.doc.namespace            = com.doc.1.0 #在Qt assistant 内容tab页的展示信息qhp.doc.virtualFolder        = docqhp.doc.indexTitle           = doc项目#qhp.doc.indexRoot           = qhp.doc.subprojects = classesqhp.doc.subprojects.classes.title = C++ Classesqhp.doc.subprojects.classes.indexTitle = C++ Classesqhp.doc.subprojects.classes.selectors = class fake:headerfileqhp.doc.subprojects.classes.sortPages = true #unknownqhp.doc.filterAttributes    = docqhp.doc.customFilters.doc.name = doc111111qhp.doc.customFilters.doc.filterAttributes = doc222222 #首页 此处使用的是title 用的是index.qdoc中的title，不使用title无法正常连接navigation.homepage = "doc Project"#navigation.landingpage = "doc"navigation.cppclassespage = "C++ Classes" #输出路径， 注意在include 的conf文件中， 可能定义路径， 因此这里使用相对路径， 未必指向“当前路径”。 outputdir   = ../html #图片路径imagedirs   = ../images #需要的图片#HTML.extraimages += image/111.jpg #把图片编译到 qhp文件中#qhp.extraFiles +=   image/111.jpg #tag文件，必需tagfile = ../doc.tags

4、添加一些基本的qdoc文件，用于进行添加页面，添加模块说明或模块划分

Qdoc文件主要用于添加一些说明文档，添加新页面，如某个模块的独立说明，或者需要在qdoc中列出所有的方法，所有的类，或自己指定的需要输出的列表等，都可在src目录下添加qdoc文件。此处需要重点说明的是，需要添加index.qdoc文件，此文件中需要添加index.html的页面，用于根节点的显示如下：

/*!\page index.html\keyword doc Reference Documentation \title doc project介绍项目XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX*/

5、生成qch/html文件

添加完基础文件和配置文件，即可生成qch文件了，在pro项目上右键，qmake，即可生成对应的qch文件。

6、使用qch文件

1、  直接打开html目录，查看。

2、  通过assistant导入使用。参见：使用qch文件。http://www.cnblogs.com/ll965452300/p/6721493.html

四、踩过的坑

1、编码问题：因为qdoc支持设置源码的编码和输出文档的编码，global/fileextensions.qdocconf中会有三个编码设置：

Naturallanguage：qdoc生成的文档使用的自然语言。包含汉子的话一般改为zh-Hans。默认为en。

Outputencoding：由qdoc生成的文档的编码。即src目录下那些文件输出的文档编码。UTF-8即可。

Sourceencoding：源代码和文档的编码。此处就是一大坑，如果qt creater中设置的gbk，此处一定要设置为GBK,如果是UTF-8那也要设置一样，并且源码文档一定要保持一个编码，否则怎么修改都会导致生成文档出现乱码。有时候出现qmake的时候报错也可能是编码问题导致。

2、assistant中doc节点为空：需要在doc.qdocconf中添加navigation.homepage = "doc Project"，并且需要在index.qdoc中的title也写为“doc Project”，因为在查找的时候使用的是title去连接的，所以必须修改为一致。

五、qdoc翻译文档