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

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

• ハウツー
• チュートリアル
• 概要
• 記事
• FAQ（よくある質問）
• 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
• \QMLattachedproperty
• \QQMLattachedproperty
• \QML型ドキュメントを作成する
• \QML type documentationを作成します。
• \QML型ドキュメントを作成する
• \QML型ドキュメントを作成する
• \を継承する
• \を継承する
• \(2)recommender(recommend)。
• \ネイティブ型

QMLタイプを文書化するには、まず、トピック・コマンドとして「QMLtype」コマン ドを使用するQDocコメントを作成します。

QML パーサー

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

QML 型をqmlファイルで文書化する場合、各 QDoc コメントは、そのコ メントが適用されるエンティティの直上に記述してください。例えば、QMLファイル内の外側のQMLタイプの直上に、(トピック・コメントである) ￤qmltypeコマンドを含むQDocコメントを配置します。QML プロパティを文書化するためのコメントはプロパティ宣言の直上に配置し、QML シグナル・ハンドラや QML メソッドについても同様に配置します。QMLパーサーは各 QDoc コメントを自動的に次の QML 宣言と関連付けるからです。QMLシグナルハンドラやQMLメソッドのコメントも同様です。例えば、プロパティのタイプが別の QML タイプで、その別の QML タイプの中の特定のプロパティのみを使用させたいが、すべてのプロパティを使用させたくない場合などです。しかし、エイリアスを持つプロパティを文書化する場合には、エイリアス宣言の真上にそのプロパティのQDocコメントを記述してください。このような場合、QDocコメントには"◆qmlproperty "コマンドを含める必要があります。

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

QML モジュール

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

QML モジュールは QML タイプをグループ化することができます。QMLモジュールでは、QMLタイプをグループ化することができます。同様に、モジュールの概要ページを作成するには、別個の.qdoc ファイルに、 ˶qmlmoduletopic コマンドが存在する必要があります。概要ページにはQMLモジュールのQMLタイプがリストアップされます。

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

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

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

readonly property int sampleReadOnlyProperty: 0

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

記事と概要

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

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

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

    \brief provides a technology never seen before.

*/

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

チュートリアル、ハウツー、FAQ

チュートリアル、How-To's、FAQ'sはすべて、読者に指示したり、処方したりするという点で、説明資料です。チュートリアルは、あるコンセプトや技術について、段階的な学習の道筋に沿って読者を導くようにデザインされたコンテンツです。How-To'sとFAQ's（Frequently Asked Questions）は、よくある質問に対する回答という形で資料を提示することで、ガイダンスを提供します。How-To'sとFAQ'sは、簡単に参照できるように設計されており、必ずしも直線的な進行で表示されるわけではありません。

これらの種類を作成するには、ページをマークするために、type 引数を 〚page 〛コマンドに与えます。type 引数は第 2 引数で、ファイル名は第 1 引数です。

/*!
    \page altruism-faq.html
    \title Altruism Frequently Asked Questions

    \brief All the questions about altruism, answered.

    ...
*/

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

コード例

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

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

QDocは、説明付きのコード例を含むページを作成します。

/*!
    \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はすべてのサンプルコードをリストアップします。