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の仕組み

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にドキュメント内のテキストや画像要素のレンダリング方法や、ドキュメントのアウトライン構造を指示します。