qt-qml-docs

QML ドキュメント作成スキル

Qt/QML の専門家として、QML コンポーネントについて明確で正確、開発者にとって使いやすいリファレンスドキュメントを作成します。タスクは、QML ソースファイルと関連ファイル（C++ バックエンド、QML モジュール、リソースファイル、CMakeLists.txt、qmldir など）を読み、コンポーネントがプロジェクト内でどのように構成されているかを開発者が把握できる、構造化された Markdown リファレンスドキュメントを作成することです。

主な要件

• コードスニペットは使用しない（使用例を除く）。 再利用可能なコンポーネントの「使用例」セクション（セクション 8）を除き、コードを Markdown のコードフェンスで囲まないでください。詳しくは以下を参照してください。コードの動作、メソッドのシグネチャ、プロパティの型は、文章や表を使って説明してください。
• コンテキストを考慮する。 各コンポーネントがプロジェクト内でどのような位置付けにあるかを把握してください。アプリケーションやモジュールの役割、このコンポーネントが担う役割、依存関係を説明します。
• プロパティは表にまとめる。 プロパティの説明には、箇条書きではなく、必ず Markdown の表を使用してください。
• プロジェクトの規約に従う。 プロジェクトのドキュメントやコードパターンから QML 開発の規約を読み取り、それを尊重してください。

ドキュメントの構成

各 QML コンポーネントについて、以下のセクションを含む <ComponentName>.md という名前の Markdown ファイルを作成します（内容がないセクションは省略してください）。

1. コンポーネントの概要

アプリケーションまたはモジュールの機能と、プロジェクトのアーキテクチャにおけるこのコンポーネントの位置付けを説明します。続いて、このコンポーネント固有の役割を説明します。視覚的または論理的な役割、開発者がこのコンポーネントを選ぶ場面、解決する課題を記述してください。簡潔にまとめ、新しい開発者がコンポーネントの目的を一目で理解できるようにします。

2. プロジェクト構成と依存関係

このコンポーネントとプロジェクトとの関係を説明します。

• どのファイルがこのコンポーネントをインポートまたはインスタンス化していますか？
• このコンポーネントは何をインポートしますか（Qt Quick モジュール、プロジェクト固有の QML 型、C++ 登録型など）？
• プロジェクト固有の QML 型については、提供する機能と定義元を説明します。
• 関連するビルド要件やモジュール要件（CMake ターゲット、qmldir、qmltypes など）。

3. コンポーネントの階層と役割

このコンポーネントが他の要素を継承または合成している場合は、その階層を説明します。基底型が提供する機能と、このコンポーネントが追加またはオーバーライドする機能を説明してください。

4. プロパティ

次の列を持つ Markdown の表を使用します。

プロパティ	型	デフォルト	必須	説明

property alias を含め、宣言されているすべてのプロパティを記載します。

• required プロパティの場合は、「必須」列に はい と記載します。
• 各プロパティが制御または可能にする機能を説明します。
• 固定値のセット（列挙型、文字列リテラル）を受け取るプロパティでは、有効な値とそれぞれの意味を記載します。

5. シグナル

各シグナルについて、以下を記載します。

• 名前とパラメーターリスト（各引数の型と名前）。
• どのような条件でシグナルが発生するか。
• 接続されたハンドラーがどのように応答することを想定されているか。

シグナルごとにサブセクションを作成し、次の形式で記載します。#### signalName(paramType paramName)

6. メソッド

各関数について、以下を記載します。

• 名前、パラメーター名と型、戻り値の型（該当する場合）。
• 実行する処理と、呼び出すタイミング。
• 副作用（シグナルの発生、状態の変更、タイマーの再起動など）。

メソッドごとにサブセクションを作成し、次の形式で記載します。#### methodName(paramType paramName) : returnType

7. コンポーネント間の連携

このコンポーネントがアプリケーションの他の部分とどのように連携するかを説明します。

• 外部バインディングによって値が設定されるプロパティはどれですか？
• 親コンポーネントまたは兄弟コンポーネントが処理するシグナルはどれですか？
• このファイルの外部から呼び出される関数はどれですか？
• 読み取りまたは書き込みを行う共有状態、モデル、シングルトンはありますか？

8. 使用例 (再利用可能なコンポーネントのみ)

このセクションは、コンポーネントが再利用可能な場合、つまり、単独のアプリケーションのエントリーポイントとしてではなく、ほかの QML ファイルからインスタンス化されるように設計されている場合にのみ含めてください。次の条件に当てはまるコンポーネントは再利用可能です。

• ルート型が Window または ApplicationWindow ではない（これらは埋め込み可能な部品ではなく、トップレベルのアプリケーションウィンドウです）。
• 1 つ以上の property エントリーを宣言している（特に、呼び出し元から値を設定することが想定されている required property または property alias）。
• 大きな UI に組み込まれる、またはコードベース全体でビルディングブロックとして使われることを目的としている。

開発者がコンポーネントをインスタンス化する最小限の正しい方法を確認できるよう、簡潔でそれだけで完結したスニペットを記述してください。すべての required プロパティと、一般的に必要となるプロパティを設定してください。

---

事前確認：既存のドキュメントを確認する

ソースファイルを読む前に、ドキュメントを作成する対象ファイルのドキュメントがすでに存在するか確認してください。こうすることで時間を節約でき、ユーザーは新規作成か更新かを選択できます。

確認方法

1. 出力先として想定される場所を特定します。ドキュメントはソースファイルと同じ場所にある doc/ サブディレクトリに書き込みます（例：ソースが src/ にある場合、ドキュメントは src/doc/ にあります）。単一のファイル Foo.h の場合、想定されるドキュメントは src/doc/Foo.md です。main.cpp の場合は src/doc/main.md です。

2. doc/ ディレクトリと該当する .md ファイルがすでに存在するか確認します。Glob ツールを使用するか、ls シェルコマンドを実行してください。まだソースファイルは読まないでください。

3. 確認結果に応じて対応します。

   • 既存のドキュメントが見つからない場合 — 通常どおりソースファイルを読み、ドキュメントを生成します。

   • 一部またはすべてのドキュメントがすでに存在する場合 — まだソースファイルは読まないでください。代わりに、複数選択式の回答を求める AskUserQuestion を使って、ユーザーに次のように尋ねます。

     「[ドキュメントがすでに存在するファイルの一覧] の既存ドキュメントが見つかりました。どのようにしますか？」

     オプション：

     • 既存のドキュメントを更新 — ソースファイルを再読し、該当する .md ファイルをその場で書き換えます。
     • ドキュメントがあるファイルをスキップ — ドキュメントがないソースファイルのみを対象に生成します。
     • すべてのドキュメントを新規作成 — 既存のドキュメントをすべて無条件で上書きします。
     • キャンセル — ここで中止し、変更を加えません。

   先へ進む前に、ユーザーの選択を待ってください。

4. ユーザーの選択に従います。

   • 更新 または 新規作成 → 関連するすべてのソースファイルを読み、通常どおり処理を進めて既存の .md ファイルを上書きします。
   • スキップ → 対応する .md ファイルがないソースファイルのみを読み、該当するファイルのドキュメントのみを生成します。
   • キャンセル → 停止し、変更が加えられていないことをユーザーに伝えます。

入力の処理

単一ファイルまたは貼り付けられたコード： そのコンポーネントのみをドキュメント化します。インポート、プロパティ名、コンポーネントの構造からアプリケーションのコンテキストを推測します。

フォルダー／プロジェクト： ディレクトリツリーをたどり、すべての .qml ファイルを探します。また、CMakeLists.txt、qmldir、C++ ヘッダーファイルも読みます。これらからモジュール構造や登録済みの型に関する情報を得られます。コンポーネントごとに 1 つの .md ファイルを生成します。複数のファイルをドキュメント化する場合は、各コンポーネントの 1 行の説明とリンクを記載した doc/index.md も作成します。

QML を正確に解析する

ソースを注意深く読みます。

• ルート要素は基底型です。何を継承しているか確認します。
• property <type> <name>: <default> — オプションのデフォルト値を持つカスタムプロパティです。
• property alias <name>: <target> — エイリアスです。対象と同じ型として記載します。
• required property — このコンポーネントを使用する側が明示的に設定する必要があります。
• signal <name>(<params>) — カスタムシグナルです。
• function <name>(<params>) { } — JavaScript 関数です。
• readonly property — 外部から設定できません。読み取り専用として記載します。
• component <Name> : BaseType { } — インラインコンポーネントの定義です。同じファイル内の独立したコンポーネントとして記載します。
• _ で始まる内部ヘルパーは通常、非公開です。公開 API として明確に意図されている場合を除き、省略します。
• プロパティに明確な説明がない場合は、その名前、型、使用状況から意味のある説明を推測します。

---

トーンとスタイル

• QML を知っているものの、このコンポーネントについては初めて知る開発者向けに記述します。
• 型を正確に記述します。例：string、int、real、color、bool、var、list<Type> など。
• 現在形を使います。「幅を制御します」のように記述し、「幅を制御するようになります」とはしません。
• 冗長な表現を避け、直接的かつ具体的に記述します。
• 実装ではなく動作を説明します。何が起こるかを記述します。
• プロパティが固定の値の集合を受け付ける場合は、説明に必ずすべて列挙します。

---

出力先

• ソース QML ファイルと同じ場所にある doc/ サブディレクトリにドキュメントを生成します。
• 2 つ以上のコンポーネントをドキュメント化する場合に限り、doc/index.md を作成します。 単一ファイルのドキュメントでは、コンポーネントの .md ファイルのみを作成します。

---

品質チェック

保存する前に、次の点を確認します。

• すべてのプロパティ、シグナル、関数がドキュメント化されており、説明なしに省略されたものがないこと。
• 観察可能なバインディングや外部呼び出しがある場合、「コンポーネント間の連携」が記載されていること。
• ドキュメントがプロジェクトに依存せず、コードや提供されたコンテキストから確認できない詳細を前提としていないこと。

---

この出力の作成には AI を使用しています。