C++ ドキュメントのスタイル

ドキュメントを生成するために、QDocはソースコードを解析し、クラスなどのC++型に関するドキュメントを生成します。その後、QDocはメンバ関数、プロパティ、その他の型を適切なクラスに関連付けます。

なお、ドキュメントは.cpp などの実装ファイル内に記述されている必要があります。

クラスのドキュメント

クラスのドキュメントは、 \class コマンドと、最初の引数として指定したクラス名を使用して生成されます。

/*!
    \class QCache
    \brief The QCache class is a template class that provides a cache.

    \ingroup tools
    \ingroup shared

    \reentrant

    QCache\<Key, T\> defines a cache that stores objects of type T
    associated with keys of type Key. For example, here's the
    definition of a cache that stores objects of type Employee
    associated with an integer key:

    \snippet code/doc_src_qcache.cpp 0

    Here's how to insert an object in the cache:

    \snippet code/doc_src_qcache.cpp 1

    ... detailed description omitted

    \sa QPixmapCache, QHash, QMap
*/

コンテキストコマンドを使用すると、モジュールやクラスが追加されたバージョンなど、クラスに関する情報を追加できます。

一般的なコンテキストコマンドには、次のようなものがあります。

\brief - クラスの簡単な説明（必須）
\since - クラスが追加されたバージョン（必須）
\internal - クラスを内部クラスとしてマークします。内部クラスは、公開APIドキュメントには表示されません。

概要と詳細な説明

概要の説明は \brief コマンドで指定され、クラスの目的や機能を要約するものです。C++ クラスについては、QDoc がそのクラスを解析し、注釈付き情報を生成します。この注釈付き情報は、クラスを表示するリストや表に表示されます。

C++の概要説明は、次のように開始する必要があります：

"The <C++ class name> class"

詳細説明セクションは、概要説明の後に続きます。ここでは、クラスに関するより詳細な情報を提供します。詳細説明には、画像、コードスニペット、または他の関連ドキュメントへのリンクを含めることができます。概要説明と詳細説明の間には、必ず1行の空白行を空ける必要があります。

メンバ関数

通常、関数のドキュメントは、.cpp ファイル内のその関数の実装の直前に記述されます。実装の直上にない関数のドキュメントについては、 \fn が必要です。

/*!
  \fn QString &QString::remove(int position, int n)

  Removes \a n characters from the string, starting at the given \a
  position index, and returns a reference to the string.

  If the specified \a position index is within the string, but \a
  position + \a n is beyond the end of the string, the string is
  truncated at the specified \a position.

  \snippet qstring/main.cpp 37

  \sa insert(), replace()
*/
QString &QString::remove(int pos, int len)

関数のドキュメントは、その関数が実行する操作を示す動詞で始まります。これはコンストラクタやデストラクタにも当てはまります。

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

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

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

戻り値の型
引数
関数の動作

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

/*!
    Returns \c true if a QScroller object was already created for \a target; \c false otherwise.

    \sa scroller()
*/
bool QScroller::hasScroller(QObject *target)

プロパティ

プロパティのドキュメントは、read関数の実装のすぐ上に記述されます。プロパティ用のtopicコマンドは \propertyです。

/*!
    \property QVariantAnimation::duration
    \brief the duration of the animation

    This property describes the duration in milliseconds of the
    animation. The default duration is 250 milliseconds.

    \sa QAbstractAnimation::duration()
 */
int QVariantAnimation::duration() const

プロパティのドキュメントは通常「このプロパティは...」で始まりますが、以下のような表現も可能です：

「このプロパティは...」
「このプロパティは……を記述しています」
「このプロパティは…を表します」
「...のときはtrue を返し、...のときはfalse を返す」 - 読み取り用のプロパティの場合。
「...を設定します」 — 型を構成するプロパティの場合。

プロパティのドキュメントには以下を含める必要があります：

プロパティの説明と動作
プロパティの許容値
プロパティのデフォルト値

関数と同様に、デフォルトの型は\c コマンドでリンクまたはマークすることができます。

値の範囲指定の例は以下の通りです：

値の範囲は 0.0（ぼかしなし）から maximumRadius（最大ぼかし）までです。デフォルトでは、このプロパティは 0.0（ぼかしなし）に設定されています。

シグナル、ノティファイア、およびスロット

シグナル、ノティファイア、およびスロットに関するトピックコマンドは次のとおりです \fnです。シグナルのドキュメントでは、それらがいつトリガーされるか、またはエミットされるかが記述されます。

/*!
  \fn QAbstractTransition::triggered()

  This signal is emitted when the transition has been triggered (after
  onTransition() has been called).
*/

シグナルのドキュメントは通常、「このシグナルは…のときにトリガーされます」という文で始まります。他の記述スタイルの例を以下に示します：

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

スロットやノティファイアについては、それらが実行される条件、あるいはシグナルによってトリガーされる条件をドキュメントに記載する必要があります。

「…のときに実行される」
「このスロットは次の場合に実行されます…」

オーバーロードされたシグナルを持つプロパティについては、QDocはオーバーロードされたノティファイアをまとめてグループ化します。特定のバージョンのノティファイアやシグナルを参照するには、単にそのプロパティを参照し、ノティファイアには異なるバージョンが存在することを明記してください。

/*!
\property QSpinBox::value
\brief the value of the spin box

setValue() will emit valueChanged() if the new value is different
from the old one. The \l{QSpinBox::}{value} property has a second notifier
signal which includes the spin box's prefix and suffix.
*/

列挙型、名前空間、およびその他の型

列挙型、名前空間、およびマクロには、ドキュメント記述用のトピックコマンドが用意されています：

これらの型に関する記述スタイルでは、まずそれが列挙型またはマクロであることを明記し、その後に型の説明を続けます。

列挙型については、 \value コマンドは値を一覧表示するために使用されます。QDocは、その列挙型の値の表を作成します。

/*!
    \enum QSql::TableType

    This enum type describes types of SQL tables.

    \value Tables  All the tables visible to the user.
    \value SystemTables  Internal tables used by the database.
    \value Views  All the views visible to the user.
    \value AllTables  All of the above.
*/

ドキュメントのカテゴリ QML ドキュメントのスタイル

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.