ステータス

これらのコマンドは、文書化された要素に何らかの特別なステータスがあることを示すためのものです。その要素は「非推奨」とマークされている可能性があります。つまり、まもなく廃止され、パブリックインターフェースから除外される予定です。 \since コマンドは、関数やクラスが最初に登場したバージョン番号を指定するために使用します。 \qmlabstract コマンドは、QML タイプを抽象基底クラスとしてマークするために使用します。

\abstract および\qmlabstract

\abstractは、\qmlabstract コマンドの同義語です。QML型を抽象基底型としてのみ使用することを意図している場合は、このコマンドをその \qmltype QML型が抽象基底型としてのみ使用されることを意図している場合、そのQML型のコメントにこのコマンドを追加してください。QML型が抽象であるということは、そのQML型がインスタンス化できないことを意味します。 その代わり、そのパブリックAPIに含まれるプロパティは、その抽象QML型を継承する各QML型のリファレンスページにあるパブリックプロパティ一覧に含められます。これらのプロパティは、あたかも継承元のQML型のプロパティであるかのように記述されます。

通常、QML タイプが \qmlabstractでマークされると、同時に \internal も付与されるため、そのリファレンスページは生成されません。抽象QML型がinternalとしてマークされていない場合、ドキュメント内にリファレンスページが作成されます。

\attribution

\attribution コマンドは、ドキュメント化された \page をライセンス帰属文書としてマークします。

\generatelist commandは、ドキュメント内のをライセンス帰属文書としてマークします。command は、ドキュメントプロジェクト内のすべてのライセンス帰属ページについて、注釈付きのリストを生成します。

\default

\default コマンドは、QML プロパティのデフォルト値をドキュメント化するために使用されます。このコマンドは単一の引数を受け取り、その引数がドキュメント上でデフォルト値として表示されます。

/*!
    \qmlproperty real Item::x
    \default 0.0
*/

デフォルト値が空でない文字列の場合は、引用符で囲んでください:

/*!
    \qmlproperty string Item::state
    \default "invalid"
*/

\compares

\compares コマンドを使用して、ドキュメントに記載されたC++型をそれ自体と比較した際の比較結果を記述してください。このコマンドは、 \class コマンドと組み合わせて使用する必要があります。

\compares は、以下のいずれかの引数を取ります：

• strong
• partial
• weak
• equality

strong、partial 、およびweak は順序に関連しています。equality は、型が等価性のみを比較することを意味します。

このコマンドは、Qt 6.7 で QDoc に導入されました。

関連項目 \compareswith。

\compareswith

\compareswith .. \endcompareswith という一連のコマンドを使用して、文書化されたC++型と他の型との比較結果を記述します。\compareswith は2つ以上の引数を取ります。具体的には、比較カテゴリに続いて型名、またはスペースで区切られた型名のリストです。\compareswith コマンドと\endcompareswith コマンドの間に記述されたテキスト行は、比較カテゴリ引数の対象となるすべての型に適用される追加の詳細情報として扱われます。

unsigned long のように、名前に1つ以上のスペースが含まれる型は、中括弧で囲む必要があります。

例：

/*!
    ...
    \compareswith strong int long {unsigned long} {unsigned int} char
    ...
    \endcompareswith
    ...
*/

中括弧で囲まれた引数については、先頭と末尾の空白が削除されます。たとえば、unsigned long とunsigned long は同等です。

比較カテゴリの引数は、以下のいずれかでなければなりません：

• strong
• partial
• weak
• equality

strong、partial 、およびweak は順序付けに関連します。equality は、型が等価であるかどうかの比較のみが行われることを意味します。

このコマンドは、Qt 6.7 以降で QDoc に導入されました。

関連項目 \compares。

\qmldefault

\qmldefault コマンドは、QMLプロパティをデフォルトのプロパティとして指定するためのものです。プロパティのドキュメントには「default 」という文字列が表示されます。

/*!
    \qmlproperty list<Change> State::changes
    This property holds the changes to apply for this state.
    \qmldefault

    By default, these changes are applied against the default state. If the state
    extends another state, then the changes are applied against the state being
    extended.
*/

State 型のリファレンスページで、QDocがこのプロパティをどのように表示するかを確認してください。

\qmlenumeratorsfrom

プロパティ型の列挙型を含むトピックで、\qmlenumeratorsfrom コマンドを使用すると、 \qmlproperty トピック内で、プロパティ型の列挙型に対してxml-ph-0000@deepl.internalコマンドを使用すると、C++の \enum トピックから列挙子のドキュメントを自動的に複製するようにしてください。

このコマンドは、完全修飾された C++ の列挙型を引数として受け取り、列挙子とその説明のリストを生成します。

デフォルトでは、各列挙子には、そのプロパティが属する型名がプレフィックスとして付加され、区切り文字として「. 」が使用されます。

例：

/*!
    \qmlproperty enumeration QtMultimedia::Camera::error
    \qmlenumeratorsfrom QCamera::Error

    //! Outputs documentation for 'Camera.NoError', 'Camera.CameraError'
*/

列挙子が QML に別の型名で登録されている場合、この名前（プレフィックス）を角括弧内のオプション引数を使用して指定することができます：

    \qmlenumeratorsfrom [Errors] QCamera::Error

    //! Outputs documentation for 'Errors.NoError', 'Errors.CameraError'
\1/

このコマンドは QDoc 6.8 で導入されました。

関連項目 \qmlproperty、 \enum、および \value。

\dontdocument

\dontdocument コマンドは、特定のモジュール用のdontdocument.qdocファイル内でのみ使用されます。このファイルには、ドキュメント化の対象外とする公開宣言されたクラスや構造体が指定されます。QDocは、これらのクラスや構造体について、\class コメントが欠落していることに関する警告を出力しません。

以下に、ウィジェット用の `dontdocument.qdoc` ファイルに含まれる `\dontdocument ` コマンドを示します：

/*!
   \dontdocument (QTypeInfo QMetaTypeId)
*/

\inheaderfile

\inheaderfile メタコマンドは、C++ クラス、名前空間、またはヘッダーファイルの参照ドキュメント用に生成された include 文を上書きするために使用されます。

デフォルトでは、QDoc は `\class SomeClass ` を、以下の `include` 文で利用可能であるものとして文書化します:

#include <SomeClass>

実際のインクルード文がデフォルトと異なる場合、次のように記述することができます。

\class SomeClass
\inheaderfile Tools/SomeClass
...

関連項目 \class および \headerfile」として文書化できます。

\obsolete

\obsolete コマンドは、\deprecated コマンドに置き換えられました。

このコマンドは、下位互換性を確保するためだけに残されています。将来の QDoc のバージョンで削除される可能性があります。代わりに `\deprecated ` コマンドを使用してください。

関連項目 \deprecated。

\deprecated

\deprecated コマンドは、関連する要素が非推奨であり、新しいコードでは使用すべきではないことを示すためのものです。

\deprecated コマンドには、2つのオプション引数があります：

• 角括弧で囲まれたバージョン番号（例：[6.2]）。
• 詳細情報を含む文字列（例：推奨される代替案など）。

クラスのリファレンスドキュメントを生成する際、QDocは非推奨のメンバを記載した別のページを作成し、そこにリンクを張ります。同等の代替案を提案しておくことが推奨されます。

/*!
    \fn MyClass::MyDeprecatedFunction
    \deprecated [6.2] Use MyNewFunction() instead.
*/

\internal

\internal コマンドは、ドキュメント化された要素がパブリックインターフェースの一部ではないことを示します。

このコマンドは、単独の行に記述する必要があります。

QDoc は、関連するクラスリファレンスドキュメントを生成する際、そのドキュメントおよびドキュメント化された項目を無視します。

/*!
    \internal

    Tries to find the decimal separator. If it can't find
    it and the thousand delimiter is != '.' it will try to
    find a '.';
*/
int QDoubleSpinBoxPrivate::findDelimiter
        (const QString &str, int index) const
{
    int dotindex = str.indexOf(delimiter, index);
    if (dotindex == -1 && thousand != dot && delimiter != dot)
        dotindex = str.indexOf(dot, index);
    return dotindex;
}

-showinternal というコマンドラインオプションを指定してQDocを呼び出すか、QDOC_SHOW_INTERNAL という環境変数が設定されていない限り、この関数はドキュメントに含まれません。

\modulestate

\module または\qmlmodule トピック内で\modulestate コマンドを使用すると、カスタムモジュール状態の説明を記述できます。

このコマンドは、モジュールの状態を記述する引数を受け取ります。例：

/*!
    \module QtFoo
    \modulestate Experimental
*/

これにより、QDocはこの情報をモジュールページに追加します:

このモジュールは「実験的」な状態にあります。

HTML出力では、このステータス情報は、モジュールのメンバーの参照ページのナビゲーションバー（ブレッドクラム）にも表示されます。

関連項目 \preliminary。

\preliminary

\preliminary コマンドは、記述された要素がまだ開発中であることを示すためのものです。

このコマンドは、単独の行に記述する必要があります。

\preliminary コマンドは、ドキュメント内の注釈に展開され、リストに要素が表示される際にその要素を「暫定」としてマークします。

/*!
    \preliminary

    Returns information about the joining type attributes of the
    character (needed for certain languages such as Arabic or
    Syriac).

*/
QChar::JoiningType QChar::joiningType() const
{
    return QChar::joiningType(ucs);
}

QDoc バージョン 6.12 以降では、\preliminary でマークされた要素について、ステータス記述子および生成される注記の内容をカスタマイズできるようになりました。

関連項目 preliminary 設定変数。

\readonly

\readonly コマンドは、 \qmlproperty コマンドと組み合わせて使用し、QMLプロパティを読み取り専用としてマークします。

\required

\required コマンドは、 \qmlproperty コマンドと組み合わせて使用し、QML プロパティを必須として指定します。

「プロパティシステム」も参照してください。

\since

\since コマンドは、関連する機能がどのマイナーリリースで追加されたかを示します。

\since に渡された引数にスペースが含まれていない場合、それは製品名の省略形であるとみなされ、QDocは生成された出力において、バージョン番号の先頭にproductname の値を付加します。productname 変数が未定義の場合、QDocはバージョン文字列のみを生成します。

引数には、製品名を明示的に含めることもできます:

\since MyFramework 2.0

この場合、引数（product および version）はそのまま使用されます。

「Since」情報の継承

QDoc バージョン 6.5 以降、C++ クラスおよび QML タイプは、タイプドキュメント内で `\since ` が明示的に使用されていない限り、それぞれのモジュールまたはQML モジュールから `\since ` ステートメントを継承します。

Since節

\value コマンドでは、コマンド文字列の直後に、角括弧で囲まれたオプションのsince節を指定することができます。これは、特定のC++列挙型の値にsince情報を付加するために使用されます。

関連項目 \value および `ignoresince`。

\wrapper

\wrapper コマンドをC++クラスのドキュメント内で使用すると、そのクラスは非Qt APIへのアクセスを提供するラッパーとしてマークされます。このコマンドは、そのようなクラスのメンバに対して通常は生成される可能性のある警告を抑制するために使用されます。