在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去連接的，所以必須修改為一致。