ドキュメントの書き方

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つのコメントで関数の全てのオーバーロードを文書化したり(複数の ˶´﹀`˵コマンドを使用)、QML プロパティグループの全てのプロパティを文書化したり(˶ ´﹀`˵コマンドを使用)することができます。

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 は書き込み可能なままにしています。

このコマンドは、ソース・ドキュメントの一部ではない記事を作成するためのものです。このコマンドは、記事のファイル名とドキュメンテーション・タイプの2つの引数を受け取ることができます。可能なタイプは以下のとおりです：

• howto
• overview
• tutorial
• faq
• attribution - ライセンスの帰属を文書化するために使用されます。
• article - タイプがない場合のデフォルト

/*!
    \page altruism-faq.html
    \title Altruism Frequently Asked Questions

    \brief All the questions about altruism, answered.

    ...
*/

トピックコマンドのページには、使用可能なすべてのトピックコマンドに関する情報があります。

トピックのコンテキスト

コンテキスト・コマンドは、QDocにトピックのコンテキストに関するヒントを与えます。例えば、あるC++関数が非推奨である場合、"deprecated "コマンドでそのようにマークする必要があります。同様に、ページ・ナビゲーションと ページ・タイトルは、QDocに余分なページ情報を与えます。

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

Context Commandsページには、利用可能なすべてのコンテキスト・コマンドのリストがあります。

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

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

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

マークアップ・コマンドのページには、使用可能なマークアップ・コマンドの完全なリストがあります。

ドキュメントの解剖学

基本的に、QDocがページを作成するためには、いくつかの必須要素が存在しなければなりません。

• QDocのコメントにトピックを割り当てる - コメントはページ、プロパティ・ドキュメンテーション、クラス・ドキュメンテーション、または利用可能なトピック・コマンドのどれかになります。
• トピックにコンテキストを与える - QDocは特定のトピックを他のページに関連付けることができます。
• マークアップコマンドでドキュメントのセクションをマークする - 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はコードの上にあるドキュメントをそのコードのドキュメントとみなします。

アーティクルは "ag娱乐注册page"コマンドを使って作成します。最初の引数はQDocが作成するHTMLファイルです。このトピックは、コンテキスト・コマンドである"\title"と "nextpage "コマンドで補足されます。その他にも、"index "コマンドや "index.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
*/

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