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

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

• \C++クラスもQMLトピックコマンドで文書化する必要があります。
• \QMLトピック・コマンドで文書化する必要があります。
• \QMLType
• \QMLMethod
• \QQMLMETHOD
• \(σ)σ(σ)σ(σ)σ
• \(σ)σσσσσσσσσσσ
• \ÕqmlmoduleÕqmlmoduleÕqmlmoduleÕqmlmoduleÕ
• \(1)neativetytype(neativtype)。
• \ネイティブ型

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

QML 型

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}

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++ 実装のどちらかにドキュメントとして記述しま す。シグナルの文書には、シグナルを発する条件、対応するシグナル・ハンドラ、シグナルが パラメータを受け付けるかどうかを記述する必要があります。

/*
    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)

関数のドキュメンテーションでよく使われる動詞をいくつか示します：

• "コピー..."- コンストラクタの場合
• "デストロイ..."- デストラクタの場合
• 「戻り値- アクセサ関数の場合

関数のドキュメントには、以下の内容を記述しなければなりません：

• 戻り値の型
• パラメータ
• 関数のアクション

関数ドキュメンテーションは、以下のことを文書化する必要があります。戻り値の型に関するドキュメントは、型に関するドキュメントにリンクするか、ブーリアン値の 場合は、" \c"コマンドでマークされなければなりません。

列挙

QML の列挙は、QML プロパティとして、"︙qmlproperty "コマンドで文書化されます。プロパティのタイプはenumeration です。列挙値を文書化するには、"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++で実装されている場合は、"enumeratorsfrom "コマンドの使用を検討してください。これが不可能な場合は、ドキュメントは対応する C++ 列挙に直接リンクすることもできます。ただし、その場合は QDoc のコメントで、列挙が C++ 列挙であることを知らせる必要があります。