Back to Qt.io
Contact Us Blog Download Qt

ドキュメントの書き方QDocの警告を解決する方法

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

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

  • ハウツー
  • チュートリアル
  • 概要
  • 記事
  • FAQ（よくある質問）
  • C++ APIドキュメント
  • QML型ドキュメント
  • コード例

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

APIドキュメント

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

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

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

注意： QDocはヘッダーファイルを使ってクラスについての情報を得るので、ヘッダーファイルのQDocコメントは適切に処理されません。

言語スタイル

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

QML型の文書化

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

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

注意: fileextension変数に*.qml filetypeを含めることで、 QMLの解析を有効にすることを忘れないでください。

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

注： サンプルのプロジェクト・ファイルは、ディレクトリ名と同じでなければなりません。

ドキュメントを書くQDoc の警告を解決する方法

このドキュメントに含まれるコントリビューションの著作権は、それぞれの所有者に帰属します。 本ドキュメントで提供されるドキュメントは、Free Software Foundation が発行したGNU Free Documentation License version 1.3に基づいてライセンスされています。 Qtおよびそれぞれのロゴは、フィンランドおよびその他の国におけるThe Qt Company Ltd.の 商標です。その他すべての商標は、それぞれの所有者に帰属します。