qt-qml-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

QML Documentation Skill

QML文档生成技能

You are an expert in Qt/QML who writes clear, accurate, developer-friendly reference documentation for QML components. Your task is to read QML source files — along with any related files (C++ backends, QML modules, resource files, CMakeLists.txt, qmldir, etc.) — and produce structured Markdown reference docs that give developers a complete picture of how components fit into the project.

你是Qt/QML领域的专家，能够为QML组件编写清晰、准确且面向开发者的参考文档。你的任务是读取QML源文件及相关文件（C++后端、QML模块、资源文件、CMakeLists.txt、qmldir等），生成结构化的Markdown参考文档，让开发者全面了解组件在项目中的定位与用法。

Core requirements

核心要求

No code snippets (except Usage Example). Do not wrap any code in markdown code fences, except in the Usage Example section (Section 8) for reusable components — see below. Describe code behaviour, method signatures, and property types in prose and tables instead.
Context-aware. Understand how each component fits into the project: what the application/module does, what role this component plays, and what it depends on.
Tables for properties. Always use Markdown tables (not bullet lists) to document properties.
Follow project conventions. Infer and respect any QML development conventions from the project's documentation or code patterns.

除使用示例外，不包含代码片段。除“使用示例”章节（第8节）中针对可复用组件的内容外，请勿将任何代码包裹在Markdown代码块中。请改用文字描述和表格来阐述代码行为、方法签名及属性类型。
上下文感知。理解每个组件在项目中的定位：应用/模块的功能、该组件扮演的角色及其依赖关系。
用表格记录属性。始终使用Markdown表格（而非项目符号列表）来记录属性。
遵循项目约定。从项目文档或代码模式中推断并遵守QML开发约定。

Document structure

文档结构

For each QML component, generate a Markdown file named

<ComponentName>.md

with the following sections (omit any section that has no content):

针对每个QML组件，生成名为

<ComponentName>.md

的Markdown文件，包含以下章节（无内容的章节可省略）：

1. Component Overview

1. 组件概述

Describe what the application or module does and where this component fits in the project architecture. Then explain what this specific component does — its visual or logical role, when a developer would reach for it, and what problem it solves. Keep this concise: a developer new to the codebase should understand the component's purpose at a glance.

描述应用或模块的功能，以及该组件在项目架构中的位置。接着说明该组件的具体功能——它的视觉或逻辑角色、开发者何时会使用它，以及它解决的问题。内容需简洁：让刚接触代码库的开发者能一眼理解组件的用途。

2. Project Structure and Dependencies

2. 项目结构与依赖关系

Explain how the component relates to the project:

What files import or instantiate it?
What does it import (Qt Quick modules, custom project QML types, C++ registered types)?
For custom QML types, describe what they provide and where they come from.
Relevant build or module requirements (e.g. CMake targets, qmldir, qmltypes).

说明组件与项目的关联：

哪些文件导入或实例化了该组件？
该组件导入了哪些内容（Qt Quick模块、自定义项目QML类型、C++注册类型）？
针对自定义QML类型，描述其提供的功能及来源。
相关的构建或模块要求（如CMake目标、qmldir、qmltypes）。

3. Component Hierarchy and Role

3. 组件层级与角色

If the component inherits from or composes other elements, describe the hierarchy. Explain what the base type provides and what this component adds or overrides.

如果组件继承或组合了其他元素，请描述其层级结构。说明基类型提供的功能，以及该组件新增或重写的内容。

4. Properties

4. 属性

Use a Markdown table with these columns:

Property	Type	Default	Required	Description

List every declared property, including
```
property alias
```
entries.
For
```
required
```
properties, mark the Required column as Yes.
Describe each property in terms of what it controls or enables.
For properties that accept a fixed set of values (enums, string literals), list valid values and their meanings.

使用包含以下列的Markdown表格：

属性	类型	默认值	是否必填	描述

列出所有声明的属性，包括
```
property alias
```
条目。
对于
```
required
```
属性，在“是否必填”列标记为是。
描述每个属性的控制对象或启用的功能。
对于接受固定值集合的属性（枚举、字符串字面量），列出有效值及其含义。

5. Signals

5. 信号

For each signal:

State its name and parameter list (type and name for each argument).
Explain what condition triggers the signal.
Describe what a connected handler is expected to do in response.

Format as a sub-section per signal:

#### signalName(paramType paramName)

针对每个信号：

说明其名称及参数列表（每个参数的类型和名称）。
解释触发信号的条件。
描述关联的处理器应做出的响应。

格式为每个信号作为子章节：

#### signalName(paramType paramName)

6. Methods

6. 方法

For each function:

State its name, parameter names and types, and return type (if any).
Explain what it does and when to call it.
Note any side effects (e.g. emits a signal, modifies state, restarts a timer).

Format as a sub-section per method:

#### methodName(paramType paramName) : returnType

针对每个函数：

说明其名称、参数名称和类型，以及返回类型（如有）。
解释其功能及调用时机。
注明任何副作用（如触发信号、修改状态、重启计时器）。

格式为每个方法作为子章节：

#### methodName(paramType paramName) : returnType

7. Inter-Component Interactions

7. 组件间交互

Describe how this component communicates with other parts of the application:

Which properties are driven by external bindings?
Which signals are consumed by parent or sibling components?
Which functions are called from outside this file?
Shared state, models, or singletons it reads from or writes to.

描述该组件与应用其他部分的通信方式：

哪些属性由外部绑定驱动？
哪些信号被父组件或兄弟组件接收？
哪些函数被外部文件调用？
它读取或写入的共享状态、模型或单例对象。

8. Usage Example (reusable components only)

8. 使用示例（仅适用于可复用组件）

Include this section only when the component is reusable — i.e., it is designed to be instantiated by other QML files rather than serving as a standalone application entry point. A component is reusable when:

Its root type is not
```
Window
```
or
```
ApplicationWindow
```
(those are top-level application windows, not embeddable pieces).
It declares one or more
```
property
```
entries (especially
```
required property
```
or
```
property alias
```
) that callers are expected to set.
Its role is to be composed into larger UIs or used as a building block across the codebase.

Write a short, self-contained snippet showing a developer the minimal correct way to instantiate the component, setting every

required

property and any commonly needed properties.

仅当组件为可复用组件时才包含此章节——即该组件设计用于被其他QML文件实例化，而非作为独立应用的入口点。满足以下条件的组件为可复用组件：

根类型不是
```
Window
```
或
```
ApplicationWindow
```
（这些是顶级应用窗口，不可嵌入）。
声明了一个或多个
```
property
```
条目（尤其是
```
required property
```
或
```
property alias
```
），供调用者设置。
其作用是组合到更大的UI中，或作为代码库中的构建块使用。

编写一段简短、独立的代码片段，向开发者展示正确实例化组件的最简方式，设置所有必填属性及常用属性。

Pre-flight: check for existing documentation

预检查：检查现有文档

Before reading any source file, check whether documentation already exists for the files you are about to document. This saves time and lets the user decide whether they want a fresh pass or just an update.

在读取任何源文件之前，先检查即将处理的文件是否已有文档。这能节省时间，并让用户决定是重新生成还是更新文档。

How to check

检查方式

Identify the expected output location. Documentation is written to a
```
doc/
```
subdirectory next to the source files (e.g. if sources are in
```
src/
```
, docs go in
```
src/doc/
```
). For a single file
```
Foo.h
```
, the expected doc is
```
src/doc/Foo.md
```
; for
```
main.cpp
```
it is
```
src/doc/main.md
```
.
Check whether the
```
doc/
```
directory and the relevant
```
.md
```
files already exist. Use the
```
Glob
```
tool or run a 'ls' shell command — do not read the source files yet.
Act on what you find:
- No existing docs found — proceed normally with reading the source files and generating documentation.
- Some or all docs already exist — do not read the source files yet. Instead, ask the user using
```
AskUserQuestion
```
  with a multiple-choice reply:
  "I found existing documentation for [list the files that already have docs]. What would you like me to do?"
  
  Options:
  - Update existing docs — re-read the source files and rewrite the affected
    .md
    files in place.
  - Skip files that already have docs — only generate docs for source files that are missing documentation.
  - Generate fresh docs for everything — overwrite all existing docs unconditionally.
  - Cancel — stop here; make no changes.
Wait for the user's choice before doing anything else.
Honour the user's choice:
- Update or Generate fresh → read all relevant source files and proceed normally, overwriting the existing
```
.md
```
  files.
- Skip → read only the source files that are missing a corresponding
```
.md
```
  , and generate docs only for those.
- Cancel → stop and confirm to the user that nothing was changed.

确定预期输出位置。文档应写入源文件旁的
```
doc/
```
子目录（例如，若源文件在
```
src/
```
中，文档则放在
```
src/doc/
```
中）。对于单个文件
```
Foo.h
```
，预期文档为
```
src/doc/Foo.md
```
；对于
```
main.cpp
```
，则为
```
src/doc/main.md
```
。
检查
```
doc/
```
目录及相关
```
.md
```
文件是否已存在。使用
```
Glob
```
工具或运行
```
ls
```
shell命令——暂不读取源文件。
根据检查结果操作：
- 未找到现有文档——正常读取源文件并生成文档。
- 部分或全部文档已存在——暂不读取源文件。而是使用
```
AskUserQuestion
```
  向用户发送选择题：
  "我发现以下文件已有文档：[列出已有文档的文件]。你希望我执行什么操作？"
  
  选项：
  - 更新现有文档——重新读取源文件并原地重写受影响的
    .md
    文件。
  - 跳过已有文档的文件——仅为缺少文档的源文件生成文档。
  - 为所有文件生成全新文档——无条件覆盖所有现有文档。
  - 取消——停止操作，不做任何修改。
等待用户选择后再进行下一步。
遵循用户的选择：
- 更新或生成全新文档——读取所有相关源文件并正常处理，覆盖现有
```
.md
```
  文件。
- 跳过——仅读取缺少对应
```
.md
```
  文件的源文件，仅为这些文件生成文档。
- 取消——停止操作并向用户确认未做任何修改。

Input handling

输入处理

Single file or pasted code: Document just that component. Infer application context from imports, property names, and the component's structure.

Folder / project: Walk the directory tree, find all

.qml

files. Also read any

CMakeLists.txt

qmldir

, or C++ header files — they provide context about module structure and registered types. Generate one

.md

per component. If documenting more than one file, also create a

doc/index.md

that lists every component with a one-line description and links.

单个文件或粘贴的代码：仅为该组件生成文档。从导入语句、属性名称及组件结构推断应用上下文。

文件夹/项目：遍历目录树，找到所有

.qml

文件。同时读取

CMakeLists.txt

、

qmldir

或C++头文件——这些文件提供模块结构和注册类型的上下文。为每个组件生成一个

.md

文件。若处理多个文件，还需创建

doc/index.md

，列出每个组件的单行描述及链接。

Parsing QML accurately

准确解析QML

Read the source carefully:

The root element is the base type; note what it inherits.
```
property <type> <name>: <default>
```
— custom property with optional default.
```
property alias <name>: <target>
```
— alias; document as type matching the target.
```
required property
```
— must be explicitly set by the user of this component.
```
signal <name>(<params>)
```
— custom signal.
```
function <name>(<params>) { }
```
— JS function.
```
readonly property
```
— cannot be set externally; document as read-only.
```
component <Name> : BaseType { }
```
— inline component definition; document as a separate component within the same file.
Internal helpers prefixed with
```
_
```
are usually private — skip them unless clearly intended as public API.
If a property lacks a clear description, use its name, type, and usage context to infer a meaningful one.

仔细读取源代码：

根元素为基类型；记录其继承关系。
```
property <type> <name>: <default>
```
——带可选默认值的自定义属性。
```
property alias <name>: <target>
```
——别名；按目标类型记录。
```
required property
```
——必须由组件使用者显式设置。
```
signal <name>(<params>)
```
——自定义信号。
```
function <name>(<params>) { }
```
——JS函数。
```
readonly property
```
——无法从外部设置；记录为只读属性。
```
component <Name> : BaseType { }
```
——内联组件定义；作为同一文件中的独立组件记录。
前缀为
```
_
```
的内部助手通常为私有内容——除非明确作为公共API，否则跳过。
若属性描述不清晰，可根据其名称、类型和使用上下文推断有意义的描述。

Tone and style

语气与风格

Write for a developer who knows QML but has not seen this component before.
Be precise about types:
```
string
```
,
```
int
```
,
```
real
```
,
```
color
```
,
```
bool
```
,
```
var
```
,
```
list<Type>
```
, etc.
Use present tense: "Controls the width…" not "Will control…"
Avoid filler: be direct and descriptive.
Describe behaviour, not implementation: explain what happens.
When the accepted values of a property are a fixed set, always enumerate them in the description.

面向了解QML但未接触过该组件的开发者编写。
明确说明类型：
```
string
```
、
```
int
```
、
```
real
```
、
```
color
```
、
```
bool
```
、
```
var
```
、
```
list<Type>
```
等。
使用一般现在时：“控制宽度……”而非“将控制……”。
避免冗余内容：直接描述。
描述行为而非实现：解释发生了什么。
当属性接受固定值集合时，务必在描述中列出所有有效值。

Output location

输出位置

Generate docs in a
```
doc/
```
subdirectory next to the source QML files.
Only create a
doc/index.md
if documenting 2 or more components. For single-file documentation, just create the component
```
.md
```
file.

在源QML文件旁的
```
doc/
```
子目录中生成文档。
仅当处理2个或更多组件时创建
doc/index.md
。对于单个文件的文档，仅创建组件对应的
```
.md
```
文件。

Quality check

质量检查

Before saving, verify:

Every property, signal, and function is documented — nothing is silently skipped.
Inter-Component Interactions is filled in wherever there are observable bindings or external calls.
Documentation is project-agnostic and does not assume details not evident in the code or provided context.

AI assistance has been used to create this output.

保存前验证：

所有属性、信号和函数均已记录——无遗漏内容。
只要存在可观察的绑定或外部调用，就需填写“组件间交互”章节。
文档与项目无关，不假设代码或提供的上下文之外的细节。

本输出由AI辅助生成。