ドキュメントのカテゴリー

あらかじめ定義されたドキュメントのカテゴリや タイプにはいくつかの種類があります：

• 記事
• C++ API ドキュメント
• QML型ドキュメント
• コード例

QDocはタイプに応じてページをフォーマットする機能を持っています。さらに、スタイルシートによって各カテゴリの表示をさらに制御することができる。

APIドキュメント

QDocはソースコードとQDocコメントのドキュメントがあれば、APIドキュメントの作成に優れています。具体的には、QDoc は Qt のアーキテクチャを認識しており、Qt C++ のクラス、関数、プロパティのドキュメントの存在を確認することができます。QDocは、コード実体にドキュメントを関連付けることができない場合や、コード実体にドキュメントがない場合に、警告やエラーを出します。

一般的に、プロパティ、クラス、メソッド、シグナル、列挙などの Qt のコード・エンティティには、対応するトピック・コマンドがあります。QDoc は、C++ の命名規則を使用してドキュメントをソースに関連付けます。

QDocはヘッダーファイル（通常は.h ）を解析して、クラス構造のツリーを構築します。その後、QDocはソース・ファイルとドキュメント・ファイルを解析し、クラス構造にドキュメントを添付します。その後、QDocはクラスのページを生成します。

言語スタイル

質の高い API ドキュメントを作成するために、Qt API リファレンスは特定の言語ガイドラインに従っています。このページの内容は、API ドキュメントの作成方法を示していますが、スタイル・ガイドラインは、リファレンス資料がどのように一貫した言語使用に従うかを示しています。

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

QML型の文書化

QML の世界では、QML シグナル、アタッチド・プロパティ、QML メソッドなど、さらに文書化が必要なエンティティがあります。内部的には Qt の技術を使用していますが、QML の API ドキュメントでは、Qt C++ API ドキュメントとは異なるレイアウトや命名規則が必要になります。

QML関連のQDocコマンドの一覧です：

• \qmlattachedproperty
• \qmlattachedsignal
• \qmlvaluetype
• \qmltype- QML 型ドキュメントの作成
• \qmlmethod
• \qmlproperty
• \qmlsignal
• \inherits
• \qmlmodule
• \inqmlmodule
• \nativetype

QMLの型を文書化するには、まず、QDocのコメントを作成します。 \qmltypeコマンドをトピックコマンドとして使用するQDocコメントを作成することから始めてください。

QMLパーサー

QMLの型がqmlファイルで定義されている場合、それを文書化します。QML 型が C++ クラスで表現されている場合は、その C++ クラスのcppファイルに記述してください。 \nativetypeコマンドでC++クラスの名前を指定してください。QML 型がqmlファイルで定義されている場合は、cppファイルに QML 型を記述しないでください。

QML 型をqmlファイルで文書化する場合、各 QDoc コメントは、そのコ メントが適用されるエンティティの直上に記述してください。たとえば \qmltypeコマンドを含む QDoc コメント（トピック・コメント）は、qmlファイルの外側の QML タイプの直上に記述してください。QML プロパティを文書化する際のコメントはプロパティ宣言の直上に置き、 QML シグナルハンドラや QML メソッドを文書化する際のコメントはプロパティ宣言の直上 に置きます。qmlファイルで QML プロパティを記述する場合、通常はトピックコマンドとして \qmlpropertyなぜなら、QMLパーサーは各QDocコメントを自動的に次のQML宣言と関連付けるからです。QMLシグナルハンドラやQMLメソッドのコメントも同様です。しかし、1つ以上のコマンドをコメントに含めると便利なことがあります。 \qmlproperty例えば、プロパティタイプが別の QML タイプであり、その別の QML タイプの中の特定のプロパティだけを使わせたいが、すべてのプロパティは使わせたくない場合などです。しかし、エイリアスを持つプロパティを文書化する場合には、そのプロパティに対するQDocコメントをエイリアス宣言の真上に置いてください。このような場合、QDocコメントには必ず\qmlpropertyコマンドを含まなければなりません。それがQDocがエイリアスのプロパティの型を知る唯一の方法だからです。

対応する C++ クラスのcppファイルで QML 型を文書化する場合（もしあれば）、通常、各 QDoc コメントは文書化するエンティティの真上に置きます。しかし、QDocではQMLパーサーを使用せず（C++パーサーを使用します）、QML QDocコメントはcppファイルのどこに記述してもかまいません。cppファイル中のQML QDocコメントは、QMLのトピックコマンドを使わなければならないことに注意してください。 \qmltypeコマンドはQML タイプの QDoc コメントに、そして \qmlpropertyコマンドは各QMLプロパティのQDocコメントに記述する必要があります。

QMLモジュール

QMLの型はモジュールに属します。モジュールは、あるプラットフォームに関連するすべての型を含んでいたり、あるバージョンの Qt Quick.例えば、Qt Quick 2 の QML 型はQt Quick 2 モジュールに属しますが、Qt 4 で導入された古い型のためのQt Quick 1 モジュールもあります。

QMLモジュールでは、QMLの型をグループ化することができます。QML モジュールでは \qmltypeトピックコマンドには \inqmlmoduleコンテキストコマンドが必要です。同様に \qmlmoduleトピックコマンドは別の.qdoc ファイルに存在しなければなりません。概要ページにはQMLモジュールのQML型が列挙されます。

そのため、QMLタイプへのリンクにはモジュール名も含まれていなければなりません。例えば、TabWidget という型がUIComponents モジュールの中にある場合、UIComponents::TabWidget とリンクする必要があります。

読み取り専用と内部QMLプロパティ

QDoc はreadonly としてマークされた QML プロパティを検出します。プロパティは値で初期化されなければならないことに注意してください。

readonly property int sampleReadOnlyProperty: 0

パブリック・インターフェイス向けでないプロパティやシグナルは \internalコマンドでマークすることができます。QDocは生成された出力にドキュメントを公開しません。

記事と概要

アーティクルとオーバービューは、トピックやコンセプトの要約を提供するのに最適なスタイルです。ある技術を紹介したり、あるコンセプトがどのように適用されるかを論じたりしますが、正確な手順をあまり詳細に論じることはありません。しかし、このタイプのコンテンツは、読者がチュートリアル、例題、クラス文書などの指導資料や参考資料を見つけるための入り口を提供することができます。概要の例としては、Qt Quick 、個々のモジュール、設計原則、ツールについてのトップレベルの議論など、製品ページが考えられます。

文書が記事であることを示すには、\page コマンドに article キーワードを追加します：

/*!
    \page overview-qt-technology.html
    \title Overview of a Qt Technology

    \brief provides a technology never seen before.

*/

トピックコマンドの書き方セクションに、使用可能な\page コマンド引数のリストがあります。

コード例

例題は、ある技術やコンセプトの実用的な使い方を示す効果的な方法です。ミドルウェアに関して言えば、これは通常、単純なコードを使ったアプリケーションの形であり、コードが何をしているのかを明確に説明するものです。どのようなモジュール、API、プロジェクト、パターンなどにも、少なくとも1つは良い例があるはずです。

例にはチュートリアルが付属していることもあります。チュートリアルはコードを指示し、説明しますが、コード例はユーザーが勉強するコード内容です。コード例には、チュートリアルにはないテキストが付随していることがあります。

QDocは \exampleコマンドを使います。

/*!
    \title UI Components: Tab Widget Example
    \example declarative/ui-components/tabwidget

    This example shows how to create a tab widget. It also demonstrates how
    \l {Property aliases}{property aliases} and
    \l {Introduction to the QML Language#Default Properties}{default properties} can be used to collect and
    assemble the child items declared within an \l Item.

    \image qml-tabwidget-example.png
*/

QDocは入力のexampledirs変数で指定されたディレクトリを使ってQtプロジェクト(.pro)ファイルを探し、サンプルファイルを生成します。生成されたHTMLはdeclarative-ui-components-tabwidget.html というファイル名になります。また、QDocはすべてのサンプルコードをリストアップします。