QDocの紹介
QDocは、Qt開発者がソフトウェアプロジェクトのドキュメントを作成するために使用するツールです。プロジェクトのソースファイルからQDocコメントを抽出し、そのコメントをHTMLページやDocBook XMLドキュメントとして整形することで動作します。QDoc は.cpp ファイルと.qdoc ファイルから QDoc コメントを見つけます。QDocは.h ファイルのQDocコメントを探しません。QDocのコメントは常に感嘆符（！）で始まります。）例えば
/*!
\class QObject
\brief The QObject class is the base class of all Qt objects.
\ingroup objectmodel
\reentrant
QObject is the heart of the Qt \l{Object Model}. The
central feature in this model is a very powerful mechanism
for seamless object communication called \l{signals and
slots}. You can connect a signal to a slot with connect()
and destroy the connection with disconnect(). To avoid
never ending notification loops you can temporarily block
signals with blockSignals(). The protected functions
connectNotify() and disconnectNotify() make it possible to
track connections.
QObjects organize themselves in \l {Object Trees &
Ownership} {object trees}. When you create a QObject with
another object as parent, the object will automatically
add itself to the parent's \c children() list. The parent
takes ownership of the object. It will automatically
delete its children in its destructor. You can look for an
object by name and optionally type using findChild() or
findChildren().
Every object has an objectName() and its class name can be
found via the corresponding metaObject() (see
QMetaObject::className()). You can determine whether the
object's class inherits another class in the QObject
inheritance hierarchy by using the \c inherits() function.
....
*/上記のQDocコメントから、QDocはHTMLのQObject class reference 。
このマニュアルでは、QDocコメントでQDocコマンドを使い、ソースファイルに良いドキュメントを埋め込む方法を説明します。また、コマンドラインでQDocに渡すQDoc設定ファイルの作り方も説明します。
QDocの実行
QDocプログラムの名前はqdoc 。コマンドラインからQDocを実行するには、設定ファイルの名前をQDocに与えます：
$ ../../bin/qdoc ./config.qdocconf
QDocは.qdocconf という接尾辞をQDoc設定ファイルとして認識します。設定ファイルはQDocにプロジェクトのソースファイル、ヘッダーファイル、.qdoc 。また、QDocにどのような出力（HTML、DocBook XML...）を生成するか、生成されたドキュメントをどこに置くかを指示する場所でもあります。設定ファイルにはQDocの他の情報も含まれています。
QDoc設定ファイルの設定方法については「QDoc設定ファイル」を参照してください。
シングル実行モードでの QDoc の実行
Qt 5.5 から、QDoc の新しい実行方法が利用できるようになり、Qt5 ドキュメントの生成にかかる時間が 90% も短縮されました。QDocの新しい実行方法はシングル実行モードです。Qt5のビルドシステムでは、単一実行モードは現在利用できません。単一実行モードはQDocを自分で実行するときにのみ利用可能で、モジュールをドキュメント化したり、他のQtモジュールとドキュメントを統合したりするときに頻繁に実行することになるでしょう。
QDocを単一実行モードで実行するには、コマンドラインに-single-exec を追加し、QDocにマスターqdocconf ファイルを渡します。このファイルは、単にすべてのQt5モジュールのqdocconfファイルのファイルパスのリストです。例えば
/Users/me/qt5/qtbase/bin/qdoc -outputdir /Users/me/qt5/qtbase/doc -installdir /Users/me/qt5/qtbase/doc /Users/me/qt5/master.qdocconf -single-exec
このqdocconfファイルmaster.qdocconf は、処理されるすべてのQt5モジュールのqdocconfファイルのリストです：
/Users/me/qt5/qtbase/src/corelib/doc/qtcore.qdocconf /Users/me/qt5/qtbase/src/network/doc/qtnetwork.qdocconf /Users/me/qt5/qtbase/src/sql/doc/qtsql.qdocconf /Users/me/qt5/qtbase/src/xml/doc/qtxml.qdocconf /Users/me/qt5/qtbase/src/testlib/doc/qttestlib.qdocconf /Users/me/qt5/qtbase/src/concurrent/doc/qtconcurrent.qdocconf /Users/me/qt5/qtbase/src/gui/doc/qtgui.qdocconf /Users/me/qt5/qtbase/src/platformheaders/doc/qtplatformheaders.qdocconf /Users/me/qt5/qtbase/src/widgets/doc/qtwidgets.qdocconf /Users/me/qt5/qtbase/src/opengl/doc/qtopengl.qdocconf /Users/me/qt5/qtbase/src/printsupport/doc/qtprintsupport.qdocconf /Users/me/qt5/qtbase/src/tools/qdoc/doc/config/qdoc.qdocconf /Users/me/qt5/qtbase/qmake/doc/qmake.qdocconf /Users/me/qt5/qtsvg/src/svg/doc/qtsvg.qdocconf /Users/me/qt5/qtxmlpatterns/src/xmlpatterns/doc/qtxmlpatterns.qdocconf /Users/me/qt5/qtdeclarative/src/qml/doc/qtqml.qdocconf /Users/me/qt5/qtdeclarative/src/quick/doc/qtquick.qdocconf /Users/me/qt5/qtquickcontrols/src/controls/doc/qtquickcontrols.qdocconf /Users/me/qt5/qtquickcontrols/src/layouts/doc/qtquicklayouts.qdocconf /Users/me/qt5/qtquickcontrols/src/dialogs/doc/qtquickdialogs.qdocconf /Users/me/qt5/qtmultimedia/src/multimedia/doc/qtmultimedia.qdocconf /Users/me/qt5/qtmultimedia/src/multimediawidgets/doc/qtmultimediawidgets.qdocconf /Users/me/qt5/qtactiveqt/src/activeqt/doc/activeqt.qdocconf /Users/me/qt5/qtsensors/src/sensors/doc/qtsensors.qdocconf /Users/me/qt5/qtwebkit/Source/qtwebkit.qdocconf /Users/me/qt5/qttools/src/assistant/help/doc/qthelp.qdocconf /Users/me/qt5/qttools/src/assistant/assistant/doc/qtassistant.qdocconf /Users/me/qt5/qttools/src/designer/src/uitools/doc/qtuitools.qdocconf /Users/me/qt5/qttools/src/designer/src/designer/doc/qtdesigner.qdocconf /Users/me/qt5/qttools/src/linguist/linguist/doc/qtlinguist.qdocconf /Users/me/qt5/qtwebkit-examples/doc/qtwebkitexamples.qdocconf /Users/me/qt5/qtgraphicaleffects/src/effects/doc/qtgraphicaleffects.qdocconf /Users/me/qt5/qtscript/src/script/doc/qtscript.qdocconf /Users/me/qt5/qtscript/src/scripttools/doc/qtscripttools.qdocconf /Users/me/qt5/qtserialport/src/serialport/doc/qtserialport.qdocconf /Users/me/qt5/qtdoc/doc/config/qtdoc.qdocconf
標準モードが遅い理由
現在、Qt5ビルドシステムはQt5ドキュメントの生成にQDocの単一実行モードを使用していません。標準モードでQDocを実行します。標準モードは、Qt5のQtのモジュール化に対応するためにQt4のQDocを変換する最も簡単な方法だったからです。Qt4では、QDocはすべてのQt4ソースに対して一度だけ実行され、QtのHTMLドキュメントを生成しました。Qt4 の QDoc は Qt ドキュメントを生成する際に、Qt のインデックスファイルも生成しました。このインデックスファイルは、Qtをベースとした他のソフトウェア・ライブラリや製品のHTMLドキュメントを生成するために、QDocを実行した後の入力として使用するためのものです。Qtのインデックスファイルによって、QDocは他のライブラリや製品用に書かれたドキュメントをQt4のドキュメントにリンクすることができました。
Qt5が登場したとき、Qtはモジュールに分割されました。それ以来、多くの新しいモジュールがQtに追加されました。バージョン5.5現在、Qt5には40以上のモジュールがあり、それぞれが他のQtモジュールのドキュメントにリンクする（依存する）独自のドキュメントを持っています。
標準モードでは、QDocは各モジュールに対して2回実行されます。特定のQtモジュールに対して最初に実行されるQDocでは、モジュールのソースファイルをすべて解析し、その情報を使ってモジュールのインデックスファイルを生成します。これはモジュールのインデックスファイルを準備するため、準備フェーズと呼ばれています。モジュールの2回目のQDocの実行も、モジュールのすべてのソースファイルを解析し、モジュールのドキュメント・ページを生成します。これはモジュールのドキュメントを生成するので、生成フェーズと呼ばれます。
モジュールのドキュメントには、他のQtモジュールのドキュメントへのHTMLリンクが含まれます。例えば、ほとんどの Qt5 モジュールはQtCore のドキュメントへのリンクを含んでいます。Qtモジュールが他のQtモジュールのドキュメントへのリンクを含んでいる場合、そのモジュールは他のQtモジュールに依存していると言えます。そのため、QDocがそのモジュールの生成フェーズを実行するときに、それらのモジュールのインデックスファイルも読み込まなければなりません。
そのため、QtビルドシステムがQtドキュメントを生成する際には、まず各モジュールに対してQDocを1回実行し、すべてのインデックスファイルを生成する準備フェーズを行います。次に、各モジュールに対してQDocを1回実行し、生成フェーズを行います。このフェーズでは、依存するインデックスファイルを使用して、モジュールのドキュメントを生成します。QDocの各実行は、準備フェーズと 生成フェーズの両方で、モジュールに含まれるすべてのソースファイルを解析し、生成フェーズでは依存モジュールのインデックスファイルも解析します。QDocの実行の間は何も保持されません。
単一実行モードがはるかに速い理由
その名の通り、単一実行モードでは Qt5 ドキュメントをすべて生成するために単一の QDoc プロセスを使用します。単一QDocプロセスは各モジュールに対して準備フェーズを行い、次に各モジュールに対して生成フェーズを行いますが、いくつかの違いがあります。まず、マスターのqdocconfファイルを読み込みます。その後、マスター・リスト内の各qdocconfファイルを読み、各モジュールの準備フェーズを実行する。準備段階では、モジュールの構文木を構築するために、モジュールのすべてのソースファイルが解析される。その後、モジュールのインデックス・ファイルが生成されますが、QDocは生成フェーズでインデックス・ファイルを再読しません。ここでの重要な違いは、インデックス・ファイルが生成された後もモジュールの構文ツリーが保持されることで、準備フェーズがすべてのモジュールに対して実行された後でも、QDocは構築したすべての構文ツリーを保持しています。
QDocはその後、生成フェーズのために各モジュールを再度処理します。しかし今度は、モジュールのシンタックス・ツリーがメモリー内に残っているので、QDocは各モジュールのソース・ファイルを再パースする必要はない。また、QDocは依存モジュールのインデックス・ファイルを再読み込みする必要もありません。あとは各モジュールのシンタックスツリーを走査してドキュメントページを生成するだけです。
したがって、QDocは各ソースファイルを一度だけ解析し、インデックスファイルを読む必要はありません。これが単一実行モードを標準モードよりもはるかに高速にしている理由です。Qtビルドシステムは最終的にQDocを単一実行モードで実行することが予想されます。しかし、マスターのqdocconfファイルの変更が必要になるかもしれないので、上で説明した単一実行モードでQDocを実行する方法は変更しなければならないかもしれません。
QDocの仕組み
QDocはまずコマンドラインで指定された設定ファイルを読み込みます。QDocは後で使うために設定ファイルからすべての変数を保存します。最初に使われる変数の一つはoutputformats です。この変数はQDocがどの出力ジェネレーターを実行するかを指示します。デフォルト値はHTMLなので、設定ファイルでoutputformats を設定しなければ、QDocはHTML出力を生成します。これは通常あなたが望むものですが、代わりにDocBookを指定してDocBook出力を得ることもできます。
次に、QDocはheaderdirs変数やheaders変数の値を使って、プロジェクトのすべてのヘッダーファイルを見つけて解析します。QDocはQDocコメントのためにヘッダーファイルをスキャンしません。QDocはヘッダーファイルを解析して、ドキュメント化すべきすべての項目、言い換えればQDocがQDocコメントを見つけるべき項目のマスターツリーを構築します。
すべてのヘッダーファイルを解析し、ドキュメント化されるべき項目のマスターツリーを構築した後、QDocはsourcedirs変数の値やsources変数の値を使用して、プロジェクトのすべての.cpp 、.qdoc ファイルを検索し、解析します。これらはQDocがQDocコメント用にスキャンするファイルです。QDocコメントは感嘆符で始まることを覚えておいてください：/*! .
QDocのコメントを見つけるごとに、マスターツリーを検索し、そのドキュメントが属するアイテムを探します。そしてコメント中のQDocコマンドを解釈し、解釈されたコマンドとコメントテキストをその項目のツリーノードに格納します。
最後に、QDocはマスター・ツリーを走査します。各ノードについて、ノードにドキュメントが保存されている場合、QDocはoutputformats 変数で指定された出力ジェネレーターを呼び出し、設定ファイルのoutputdir変数で指定されたディレクトリにドキュメントをフォーマットして書き込みます。
コマンドの種類
QDocは3種類のコマンドを解釈します：
トピック・コマンドは、ドキュメント化する要素を特定します。たとえば、C++クラス、関数、型、または基礎となるC++要素にマッピングされない余分なページのテキストなどです。
コンテキスト・コマンドは、ドキュメント化されている要素が他のドキュメント化された要素にどのように関連しているかを QDoc に伝えます。コンテキスト・コマンドは、QDocがソース・ファイルから得ることのできない、ドキュメント化された要素に関する情報を提供することもできます。たとえば、その要素がスレッドセーフかどうか、オーバーロードされた関数かどうか、再実装された関数かどうか、非推奨になったかどうかなどです。
マークアップコマンドはQDocにドキュメント内のテキストや画像要素のレンダリング方法やドキュメントのアウトライン構造を指示します。
本ドキュメントに含まれる文書の著作権は、それぞれの所有者に帰属します。 本書で提供されるドキュメントは、Free Software Foundation が発行したGNU Free Documentation License version 1.3に基づいてライセンスされています。 Qtおよびそれぞれのロゴは、フィンランドおよびその他の国におけるThe Qt Company Ltd.の 商標です。その他すべての商標は、それぞれの所有者に帰属します。
