QML ドキュメントスタイル

QDocは、C++クラスとして定義されたQML型と、.qml ファイルで定義されたQML型の両方を処理できます。QML型としてドキュメント化されたC++クラスについては、QDocコメントは.cpp ファイルに記述され、QMLで定義されたQML型については.qml ファイルに記述されます。また、C++クラスについては、以下のQMLトピックコマンドを使用してドキュメント化する必要があります：

• \qmlattachedmethod
• \qmlattachedproperty
• \qmlattachedsignal
• \qmlvaluetype
• \qmltype
• \qmlmethod
• \qmlproperty
• \qmlsignal
• \qmlmodule
• \inqmlmodule
• \nativetype

.qml ファイルで定義された QML タイプの場合、QDoc は QML を解析し、QML 定義内のプロパティ、シグナル、および型を判別します。この場合、QDoc ブロックは宣言の直上に配置する必要があります。 C++で実装されたQML型の場合、C++クラスのドキュメントが存在しない場合、QDocは警告を出力します。クラスのドキュメントは、パブリックAPIでない場合、「internal」としてマークすることができます。

QML 型

\qmltype コマンドは、QML 型のドキュメント作成に使用します。

    \qmltype TextEdit
    \nativetype QQuickTextEdit
    \inqmlmodule QtQuick
    \ingroup qtquick-visual
    \ingroup qtquick-input
    \inherits Item
    \brief Displays multiple lines of editable formatted text

    The TextEdit item displays a block of editable, formatted text.

    It can display both plain and rich text. For example:

    \qml
        TextEdit {
            width: 240
            text: "<b>Hello</b> <i>World!</i>"
            font.family: "Helvetica"
            font.pointSize: 20
            color: "blue"
            focus: true
        }
    \endqml

    \image declarative-textedit.gif

    ... omitted detailed description

    \sa Text, TextInput, {examples/quick/text/textselection}{Text Selection example}

`QMLType` \nativetype コマンドは、引数として QML 型を実装する C++ クラスを受け取ります。QML で実装された型の場合、これは必要ありません。

概要は、QML 型の要約となります。概要は完全な文である必要はなく、動詞で始まっても構いません。QDoc は、表や生成されたリスト内で、この概要を QML 型に付加します。

\qmltype ColorAnimation
\brief Animates changes in color values

以下に、概要文で使用できる動詞の例をいくつか挙げます：

• 「...を提供する」
• 「指定する...」
• 「説明する...」

詳細な説明は概要の後に続き、画像、コードスニペット、および他のドキュメントへのリンクを含めることができます。

プロパティ

プロパティの説明は、そのプロパティの機能に焦点を当てており、次のような形式が用いられる場合があります：

プロパティのドキュメントは通常「このプロパティは…」で始まりますが、特定のプロパティについては、以下のような表現がよく使われます：

• 「このプロパティは...を保持します」
• 「このプロパティは…を記述します」
• 「このプロパティは…を表します」
• 「...のときはtrue を返し、...のときはfalse を返す」 -read-only とマークされたプロパティの場合。
• 「...を設定する」 — 型を構成するプロパティの場合。

シグナルとハンドラのドキュメント

QMLシグナルは、QMLファイル内、またはC++実装内の \qmlsignal コマンドを使用して、QML ファイルまたは C++ 実装のいずれかに記述されます。シグナルのドキュメントには、シグナルを発行するための条件、対応するシグナルハンドラ、およびシグナルがパラメータを受け入れるかどうかを記載する必要があります。

/*
    This signal is emitted when the user clicks the button. A click is defined
    as a press followed by a release. The corresponding handler is
    \c onClicked.
*/
signal clicked()

シグナルで可能なドキュメント形式は以下の通りです。

• 「このシグナルは、...のときにトリガーされます」
• 「…のときにトリガーされます」
• 「…のときに発信される」

メソッドと QML 関数

通常、関数のドキュメントは、.cpp ファイル内のその関数の実装の直前に記述されます。関数に対するtopicコマンドは\fnです。QML内の関数については、ドキュメントは関数宣言の直上に記述する必要があります。

関数のドキュメントは、その関数が実行する操作を示す動詞から始まります。

/*
    \qmlmethod QtQuick2::ListModel::remove(int index, int count = 1)

    Deletes the content at \a index from the model.

    \sa clear()
*/
void QQuickListModel::remove(QQmlV8Function *args)

関数のドキュメントでよく使われる動詞の例：

• 「コピーする...」 - コンストラクタ用
• 「破棄する...」 - デストラクタ用
• 「...を返す」 - アクセサ関数用

関数のドキュメントには、以下の情報を記載する必要があります：

• 戻り値の型
• パラメータ
• 関数の動作

\a コマンドを使用すると、ドキュメント内でそのパラメータがマークされます。戻り値の型に関するドキュメントは、型のドキュメントへのリンクを設けるか、ブール値の場合は \c コマンドでマークされるべきです。

列挙型

QML の列挙型は、 \qmlenum コマンドを使用して記述されます。列挙型の値を記述するには \value コマンドを使用して、列挙型の値をドキュメント化します。QDocはこれを自動的に行わないため、各値の先頭にピリオド（.）で区切って型名をプレフィックスとして追加してください。

/*!
\qmlproperty enumeration QtQuick2::Text::font.weight

Sets the font's weight.

The weight can be one of:
\value Font.Light
\value Font.Normal      The default
\value Font.DemiBold
\value Font.Bold
\value Font.Black

QDoc コメントには、列挙型の値が一覧表示されます。

列挙型が C++ で実装されている場合は、 \qmlenumeratorsfrom コマンドの使用を検討してください。それが不可能な場合は、ドキュメントから対応するC++の列挙型へ直接リンクを張ることも可能です。ただし、その場合はQDocコメント内で、その列挙型がC++の列挙型であることを明記する必要があります。