在Qt示例項目的C ++ / QML源中的//！ [0]的含義是什麼？

在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 語法

 

 

1、介紹什麼是qdoc

Qdoc是開發者用於在軟件工程中生成文檔的一個工具。它從工程的源文件中提取qdoc類型註釋，並以html頁面或者DITA XML文檔的形式格式化到文件中。Qdoc在.cpp和.qdoc文件中查找註釋，而不會在.h文件中查找。一條qdoc註釋每每以一個前置聲明符號（!）開始。

2、使用qdoc的好處和缺點

優勢：

a) 經過qdoc自動提取註釋生成開發文檔。

b) 在對外接口中可直接經過qdoc生成文檔作接口文件，不用單獨再寫文檔。

c) 將代碼邏輯寫到註釋中，便於修改代碼時修改。避免了以前單獨出代碼文檔時修改代碼忘記更新文檔，形成文檔代碼不一致。

d) 支持多種格式輸出，qch，html等格式，便於不一樣閱讀方式。

缺點：

a)         必須按照qdoc的格式編寫註釋，而且註釋必須與代碼一致。

b)         Qdoc不能生成對私有函數註釋輸出（可經過修改源代碼輸出）。

c)         使用人數較少，網上文檔較少，通常只能看官方文檔。

3、建立Qdoc工程

一、 建立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

二、添加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中介紹。

三、添加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

四、添加一些基本的qdoc文件，用於進行添加頁面，添加模塊說明或模塊劃分

Qdoc文件主要用於添加一些說明文檔，添加新頁面，如某個模塊的獨立說明，或者須要在qdoc中列出全部的方法，全部的類，或本身指定的須要輸出的列表等，均可在src目錄下添加qdoc文件。此處須要重點說明的是，須要添加index.qdoc文件，此文件中須要添加index.html的頁面，用於根節點的顯示以下：

/*!

\page index.html

\keyword doc Reference Documentation

 \title doc project

介紹項目XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

*/

五、生成qch/html文件

添加完基礎文件和配置文件，便可生成qch文件了，在pro項目上右鍵，qmake，便可生成對應的qch文件。

六、使用qch文件

一、  直接打開html目錄，查看。

二、  經過assistant導入使用。參見：使用qch文件。http://www.cnblogs.com/ll965452300/p/6721493.html

4、踩過的坑

一、編碼問題：由於qdoc支持設置源碼的編碼和輸出文檔的編碼，global/fileextensions.qdocconf中會有三個編碼設置：

Naturallanguage：qdoc生成的文檔使用的天然語言。包含漢子的話通常改成zh-Hans。默認爲en。

Outputencoding：由qdoc生成的文檔的編碼。即src目錄下那些文件輸出的文檔編碼。UTF-8便可。

Sourceencoding：源代碼和文檔的編碼。此處就是一大坑，若是qt creater中設置的gbk，此處必定要設置爲GBK,若是是UTF-8那也要設置同樣，而且源碼文檔必定要保持一個編碼，不然怎麼修改都會致使生成文檔出現亂碼。有時候出現qmake的時候報錯也多是編碼問題致使。

二、assistant中doc節點爲空：須要在doc.qdocconf中添加navigation.homepage = "doc Project"，而且須要在index.qdoc中的title也寫爲「doc Project」，由於在查找的時候使用的是title去鏈接的，因此必須修改成一致。

5、qdoc翻譯文檔