ドキュメントの作成

QDocのコメント

ドキュメントは、/*! および */ で囲まれた QDocコメント内に記述されます。これらは C++ および QML において有効なコメントであることに注意してください。

QDocコメント内では、//! が1行のドキュメントコメントとして使用されます。このコメント自体およびその後に続く改行までの内容は、生成された出力から省略されます。

QDocは、C++およびQMLファイルを解析してQDocコメントを検索します。特定のファイルタイプを明示的に除外するには、設定ファイルからそのファイルタイプを除外してください。

QDoc コマンド

QDoc は、ドキュメントに関する情報を取得するためにコマンドを使用します。Topic コマンドはドキュメント要素のタイプを判別し、context コマンドはトピックに関するヒントや情報を提供し、markup コマンドは QDoc がドキュメントの一部をどのようにフォーマットすべきかに関する情報を提供します。

QDocのトピック

各QDocコメントには、トピックタイプを指定する必要があります。トピックは、そのコメントを他のトピックと区別するためのものです。トピックタイプを指定するには、いくつかのトピックコマンドのいずれかを使用します。

QDocは類似したトピックを収集し、それぞれについてページを作成します。たとえば、特定のC++クラスのすべての列挙型、プロパティ、関数、およびクラス記述は、1つのページにまとめられます。汎用ページは \page コマンドを使用して指定し、引数としてファイル名を指定します。

トピックコマンドの例：

• \enum - 列挙型のドキュメントの場合
• \class - C++クラスのドキュメント用
• \qmltype - QML型のドキュメント用
• \page - ページの作成用。

複数のトピック

QDocコメントには、いくつかの制限はあるものの、同じカテゴリ内の複数のトピックコマンドを含めることができます。これにより、1つのコメントで関数のすべてのオーバーロード（複数の \fn コマンド）を使用することで、1つのコメントで関数のすべてのオーバーロードを記述したり、 \qmlproperty コマンドを使用）を一度に記述することが可能です。

QDocコメントに複数のトピックコマンドが含まれている場合、後続のコメントで個々のトピックに対して追加のコンテキストコマンドを指定することが可能です：

/*!
    \qmlproperty string Type::element.name
    \qmlproperty int Type::element.id

    \brief Holds the element name and id.
*/

/*!
    \qmlproperty int Type::element.id
    \readonly
*/

ここでは、後続のコメントによってelement.idプロパティが読み取り専用に設定される一方、element.name は書き込み可能なままとなります。

「トピックコマンド」ページには、利用可能なすべてのトピックコマンドに関する情報が掲載されています。

トピックのコンテキスト

コンテキストコマンドは、トピックの文脈に関するヒントをQDocに提供します。たとえば、C++の関数が非推奨となっている場合、 \deprecated コマンドを使用して、その旨を明記する必要があります。同様に、ページナビゲーションやページタイトルも、QDocに追加のページ情報を提供します。

QDocは、これらのコンテキストに基づいて追加のリンクやページを作成します。例えば、 \group コマンドを使用してグループが作成され、メンバーには \ingroup コマンドが指定されます。グループ名は引数として指定されます。

「コンテキストコマンド」ページには、利用可能なすべてのコンテキストコマンドの一覧が掲載されています。

ドキュメントのマークアップ

QDocは、他のマークアップツールやドキュメント作成ツールと同様に、テキストのマークアップを行うことができます。QDocでは、テキストに \b コマンドでマークアップされている場合、そのテキストの一部を太字に表示できます。

\b{This} text will be in \b{bold}.

「マークアップコマンド」ページには、利用可能なマークアップコマンドの完全な一覧が掲載されています。

ドキュメントの構成

基本的に、QDocがページを作成するには、いくつかの必須要素が存在している必要があります。

• QDocコメントにトピックを割り当てる - コメントは、ページ、プロパティのドキュメント、クラスのドキュメント、あるいは利用可能なトピックコマンドのいずれかです。
• トピックにコンテキストを指定する — QDoc は、特定のトピックを他のページに関連付けることができます。例えば、ドキュメントに \deprecatedでマークされたドキュメントに非推奨要素を関連付けるなど、特定のトピックを他のページに関連付けることができます。
• ドキュメントのセクションにマークアップコマンドを指定する - QDoc は、ドキュメントのレイアウトを作成し、書式設定を行うことができます。

Qt XMLでは、QVector3D クラスは次のQDocコメントでドキュメント化されていました：

/*!
    \class QVector3D
    \brief The QVector3D class represents a vector or vertex in 3D space.
    \since 4.6
    \ingroup painting-3D

    Vectors are one of the main building blocks of 3D representation and
    drawing.  They consist of three coordinates, traditionally called
    x, y, and z.

    The QVector3D class can also be used to represent vertices in 3D space.
    We therefore do not need to provide a separate vertex class.

    \note By design values in the QVector3D instance are stored as \c float.
    This means that on platforms where the \c qreal arguments to QVector3D
    functions are represented by \c double values, it is possible to
    lose precision.

    \sa QVector2D, QVector4D, QQuaternion
*/

このクラスにはコンストラクタ `QVector3D::QVector3D()` があり、これについては以下の QDoc コメントで説明されていました：

/*!
    \fn QVector3D::QVector3D(const QPoint& point)

    Constructs a vector with x and y coordinates from a 2D \a point, and a
    z coordinate of 0.
*/

異なるコメントは異なるファイルに存在する場合がありますが、QDocはトピックや文脈に応じてそれらを収集します。スニペットから生成されたドキュメントは、QVector3D クラスのドキュメントとして生成されます。

なお、ドキュメントがソースコード内の関数やクラスの直前にある場合、トピックを指定する必要はありません。QDocは、コードの上にあるドキュメントをそのコードに関するドキュメントであるとみなします。

記事は \page コマンドを使用して作成されます。最初の引数は、QDocが生成するHTMLファイルです。トピックには、コンテキストコマンドである \title および \nextpage コマンドによってトピックに情報が追加されます。他にも、 \list コマンドなど、他にもいくつかのQDocコマンドがあります。

/*!
    \page generic-guide.html
    \title Generic QDoc Guide
    \nextpage Creating QDoc Configuration Files
    There are three essential materials for generating documentation with QDoc:

    \list
        \li \c QDoc binary (\c {qdoc})
        \li \c qdocconf configuration files
        \li \c Documentation in \c C++, \c QML, and \c .qdoc files
    \endlist
*/

トピックコマンドに関するセクションでは、その他のいくつかのトピックタイプについて概要を説明しています。