在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 minimal
QDOC_BIN = $$shell_path($$[QT_INSTALL_BINS]/qdoc)
QDOC_PREPARE = $$QDOC_BIN -prepare
QDOC_GENERATE = $$QDOC_BIN -generate
QDOC_GLOBAL = QT_INSTALL_DOCS=$$[QT_INSTALL_DOCS]/src
QDOC_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}.qhp
QCH_FILE = $$PROJECT_PWD/$${TargetName}.qch
 
doc_generate.TARGET = $$TargetName.qhp
doc_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.qch
qch_docs.commands = $$HELPGENERATOR -o $$QCH_FILE $$QHP_FILE
qch_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                 = doc
qhp.doc.file                 = doc.qhp
qhp.doc.namespace            = com.doc.1.0
 
#在Qt assistant 内容tab页的展示信息
qhp.doc.virtualFolder        = doc
qhp.doc.indexTitle           = doc项目
#qhp.doc.indexRoot           =
 
qhp.doc.subprojects = classes
qhp.doc.subprojects.classes.title = C++ Classes
qhp.doc.subprojects.classes.indexTitle = C++ Classes
qhp.doc.subprojects.classes.selectors = class fake:headerfile
qhp.doc.subprojects.classes.sortPages = true
 
#unknown
qhp.doc.filterAttributes    = doc
qhp.doc.customFilters.doc.name = doc111111
qhp.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翻译文档