ドキュメントのカテゴリ

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

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

QDocには、タイプに応じてページのレイアウトを調整する機能があります。さらに、スタイルシートを使用することで、各カテゴリの表示をさらに細かく制御することができます。

APIドキュメント

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

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

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

言語スタイル

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

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

QML 型のドキュメント作成

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

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

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

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

QML パーサー

QML タイプがqmlファイルで定義されている場合は、そのファイル内でドキュメントを作成してください。QML タイプが C++ クラスで表現されている場合は、その C++ クラスのcppファイル内でドキュメントを作成し、 \nativetype コマンドを含めて、C++クラスの名前を指定してください。QMLタイプがqmlファイルで定義されている場合は、cppファイル内でそのQMLタイプをドキュメント化しないでください。

qmlファイル内で QML タイプをドキュメント化する場合は、各 QDoc コメントを、そのコメントが適用されるエンティティの直上に配置してください。たとえば、qml ファイル内の外側の QML タイプの直上に、 \qmltype コマンド（トピックコメント）を含むQDocコメントは、qmlファイル内の外側のQML型の直上に配置してください。QMLプロパティをドキュメント化するコメントはプロパティ宣言の直上に配置し、QMLシグナルハンドラやQMLメソッドについても同様に扱ってください。なお、qmlファイル内でQMLプロパティをドキュメント化する際、通常は \qmlproperty コマンドをトピックコマンドとして含める必要はありません（cppファイル内でQML型をドキュメント化する場合はこれを行う必要があります）。これは、QMLパーサーが各QDocコメントを、次に解析されるQML宣言と自動的に関連付けるためです。QMLシグナルハンドラやQMLメソッドのコメントについても同様です。ただし、場合によっては、コメント内に1つ以上の \qmlproperty `qdoc`コマンドを含めることが役立つ場合があります。例えば、プロパティの型が別のQML型であり、その別のQML型内の特定のプロパティのみを使用させ、すべてのプロパティを使用させたくない場合などです。 ただし、エイリアスを持つプロパティをドキュメント化する場合は、そのQDocコメントをエイリアスの宣言の直上に配置してください。このような場合、QDocコメントには\qmlproperty コマンドを含める必要があります。なぜなら、それだけがQDocがエイリアスされたプロパティの型を認識できる唯一の方法だからです。

対応する C++ クラスのcppファイル（存在する場合）で QML タイプをドキュメント化する場合は、通常、各 QDoc コメントを、それがドキュメント化するエンティティのすぐ上に配置します。 ただし、QDoc はこれらのファイルを解析する際に QML パーサーを使用しない（C++ パーサーが使用される）ため、これらの QML QDoc コメントはcppファイル内のどこにでも配置できます。cppファイル内の QML QDoc コメントでは、QML の topic コマンドを使用する必要があることに注意してください。つまり、 \qmltype コマンドはQML型のQDocコメント内に記述され、 \qmlproperty コマンドは、各 QML プロパティの QDoc コメント内に記述する必要があります。

QML モジュール

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

QMLモジュールを使用すると、QML型をグループ化できます。 \qmltype topic コマンドには、 \inqmlmodule contextコマンドを伴い、その型をQMLモジュールに関連付ける必要があります。同様に、 \qmlmodule topic コマンドは、そのモジュールの概要ページを作成するために、別の.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 Project（.pro ）ファイルを検索し、サンプルファイルを生成します。生成されたHTMLファイル名はdeclarative-ui-components-tabwidget.html となります。また、QDocはすべてのサンプルコードを一覧表示します。