QDocの概要

QDocは、Qt開発者がソフトウェアプロジェクトのドキュメントを生成するために使用するツールです。プロジェクトのソースファイルからQDocコメントを抽出し、それらをHTMLページやDocBook XMLドキュメントとしてフォーマットすることで機能します。 QDocは、.cpp ファイルおよび.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 を実行するには、設定ファイルの名前を指定します：

$ ../../bin/qdoc ./config.qdocconf

QDocは、.qdocconf という拡張子を持つファイルをQDoc設定ファイルとして認識します。この設定ファイルでは、プロジェクトのソースファイル、ヘッダーファイル、および.qdoc ファイルの場所をQDocに指定します。また、生成する出力形式（HTML、DocBook XMLなど）や、生成されたドキュメントの保存先もここで指定します。 設定ファイルには、QDocに関するその他の情報も含まれています。

QDoc設定ファイルの設定方法については、「QDoc設定ファイル」を参照してください。

QDocの動作

QDocは、まずコマンドラインで指定された設定ファイルを読み込みます。その後、後で使用するために設定ファイル内のすべての変数を保存します。 最初に使用される変数の 1 つが `outputformats` です。この変数は、QDoc がどの出力ジェネレータを実行するかを指定します。デフォルト値はHTML であるため、設定ファイルで `outputformats ` を設定しない場合、QDoc は HTML 出力を生成します。通常はこれで十分ですが、代わりに DocBook 出力を得るために`DocBook`を指定することも可能です。

次に、QDocは `headerdirs` 変数および/または`headers` 変数の値を使用して、プロジェクトのすべてのヘッダーファイルを探し出し、解析します。 QDocは、ヘッダーファイル内のQDocコメントをスキャンしません。ヘッダーファイルを解析して、ドキュメント化すべきすべての項目、つまりQDocがQDocコメントを見つけるべき項目のマスターツリーを構築します。

すべてのヘッダーファイルを解析し、ドキュメント化対象項目のマスターツリーを構築した後、QDocはsourcedirs変数および /またはsources変数の値を使用して、プロジェクトのすべての.cpp および.qdoc ファイルを見つけ出し、解析します。これらは、QDocがQDocコメントをスキャンする対象となるファイルです。 QDoc コメントは感嘆符「!/*」で始まることに注意してください。

QDocコメントが見つかるたびに、QDocはマスターツリー内を検索して、そのドキュメントが属する項目を探します。その後、コメント内のQDocコマンドを解釈し、解釈されたコマンドとコメントテキストを、その項目のツリーノードに格納します。

最後に、QDoc はマスターツリーを走査します。各ノードについて、そのノードにドキュメントが保存されている場合、QDoc はoutputformats 変数で指定された出力ジェネレータを呼び出し、設定ファイルのoutputdir変数で指定されたディレクトリにドキュメントをフォーマットして書き込みます。

コマンドの種類

QDocは3種類のコマンドを解釈します：

• トピックコマンド
• コンテキストコマンド
• マークアップコマンド

トピックコマンドは、ドキュメント化対象の要素（たとえば、C++のクラス、関数、型、あるいは基盤となるC++要素に対応しない追加のテキストページなど）を特定します。

コンテキストコマンドは、ドキュメント化対象の要素が他のドキュメント化された要素とどのように関連しているかを QDoc に伝えます。例えば、次ページや前ページへのリンク、ページグループへの包含、ライブラリモジュールなどです。 コンテキストコマンドは、QDoc がソースファイルからは取得できない、ドキュメント化対象の要素に関する情報を提供することもできます。たとえば、その要素がスレッドセーフであるかどうか、オーバーロードまたは再実装された関数であるかどうか、あるいは非推奨になっているかどうかなどです。

マークアップコマンドは、文書内のテキストや画像要素をどのようにレンダリングすべきか、あるいは文書のアウトライン構造について、QDoc に指示します。