QMLドキュメントのスタイル

QDocはC++クラスとして定義されたQML型と、.qml ファイルで定義されたQML型を処理することができます。QML 型として文書化された C++ クラスの場合、QDoc のコメントは.cpp ファイルにあり、QML で定義された QML 型は.qml ファイルにあります。また、C++ クラスは QML のトピックコマンドで文書化する必要があります：

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

.qml ファイルで定義された QML 型については、QDoc は QML を解析し、プロパティ、シグナル、QML 定義内の型を決定します。QDocはQMLを解析し、QML定義内のプロパティ、シグナル、型を決定します。C++で実装されたQMLの型については、C++のクラス文書が存在しない場合、QDocは警告を出力します。クラスのドキュメントがパブリックAPIでない場合は、内部ドキュメントとしてマークされることがあります。

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}

この \nativetypeコマンドは QML 型を実装した C++ クラスを引数にとります。QMLで実装された型については、このコマンドは必要ありません。

brief descriptionはQML型の概要を記述します。説明文は完全な文章である必要はなく、動詞で始めてもかまいません。QDocは表や生成されたリストの中で、QMLの型に簡単な説明を加えます。

\qmltype ColorAnimation
\brief Animates changes in color values

以下は簡潔な説明のための代替動詞です：

• "提供する..."
• "指定する..."
• "記述する..."

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

プロパティ

プロパティの説明は、プロパティが何をするかに焦点を当て、以下のスタイルを使用することができます：

プロパティのドキュメントは通常、"This property... "で始まりますが、特定のプロパティについては、これらの表現が一般的です：

• "このプロパティは..."
• "このプロパティは... "を記述する。
• "このプロパティは..."
• "・・・のときtrue を返し、・・・のときfalse を返す"- と表示されているプロパティについては、read-only 。
• 「を設定します。- 型を設定するプロパティの場合。

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

QMLのシグナルは、QMLファイルもしくはC++の実装の中で \qmlsignalコマンドで記述します。シグナルのドキュメントには、シグナルが発生する条件、対応するシグナルハンドラ、 そしてシグナルがパラメータを受け付けるかどうかを記述しなければなりません。

/*
    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 ファイル内の関数の実装の直前に記述します。関数のトピックコマンドは\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 の列挙型は、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++の列挙であることを知らせる必要があります。