ドキュメントの書き方

QDocコメント

ドキュメントはQDocコメントの中に含まれます。これらはC++やQMLで有効なコメントであることに注意してください。

QDocコメント内では、//! が1行のドキュメント・コメントとして使用されます。コメントそのものと、それ以降（改行まで）は、生成される出力から省略されます。

QDocはC++とQMLファイルを解析してQDocコメントを探します。特定のファイル・タイプを明示的に省略するには、設定ファイルから省略してください。

QDocコマンド

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

QDocのトピック

QDocの各コメントはトピック・タイプを持たなければならない。トピックは他のトピックと区別します。トピック・タイプを指定するには、いくつかのトピック・コマンドのうちの1つを使用してください。

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

トピック・コマンドの例

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

複数のトピック

QDocのコメントには、いくつかの制限はありますが、同じカテゴリの複数のトピックコマンドを含めることができます。こうすることで、ある関数のすべてのオーバーロードを1つのコメントで記述したり（複数の \fnコマンドを使用)、あるいは QML プロパティグループ内のすべてのプロパティ(コマンドを使用)を一度に文書化するコメントを書くことができます。 \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では、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() があります：

/*!
    \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コマンドで補足される。コマンドのような他のQDocコマンドもいくつかあります。 \listコマンドがあります。

/*!
    \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
*/

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