SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场qt-qml-docs

qt-qml-docs

编程与开发

查看项目

更新于 10-15 14:52

技能介绍

用途

qt-qml-docs 是一个面向 Qt/QML 的文档生成技能，用于为 QML 组件和应用生成独立的 Markdown 参考文档。它读取 QML 源文件以及相关文件（C++ 后端、QML 模块、资源文件、CMakeLists.txt、qmldir 等），产出结构化的 Markdown 参考文档，让开发者完整了解组件如何融入项目。

主要能力

  • 为每个 QML 组件生成一个以 <ComponentName>.md 命名的 Markdown 文件。
  • 文档结构包含以下章节（无内容的章节会被省略）：
    1. 组件概述：说明应用或模块做什么、该组件在项目架构中的位置，以及该组件自身的作用。
    2. 项目结构与依赖：说明哪些文件导入或实例化它、它导入了什么（Qt Quick 模块、自定义 QML 类型、C++ 注册类型）、自定义 QML 类型提供什么及来源、相关构建或模块要求（如 CMake 目标、qmldir、qmltypes）。
    3. 组件层级与角色：若组件继承或组合其他元素，说明层级关系、基类型提供什么、该组件新增或覆盖了什么。
    4. 属性：使用 Markdown 表格，列为 Property、Type、Default、Required、Description；列出所有声明的属性（含 property alias）；required 属性在 Required 列标为 Yes；对接受固定取值集合的属性列出有效值及含义。
    5. 信号：每个信号以 #### signalName(paramType paramName) 子章节说明名称与参数列表、触发条件、连接处理程序应做什么。
    6. 方法：每个函数以 #### methodName(paramType paramName) : returnType 子章节说明名称、参数名与类型、返回类型、作用与调用时机、副作用（如发出信号、修改状态、重启定时器）。
    7. 组件间交互：说明哪些属性由外部绑定驱动、哪些信号被父级或同级组件消费、哪些函数被外部调用、读取或写入的共享状态、模型或单例。
    8. 使用示例（仅可复用组件）：仅当组件可复用（根类型不是 Window 或 ApplicationWindow、声明了一个或多个供调用方设置的属性、角色是被组合进更大 UI 或作为构建块）时，给出最小正确实例化片段，设置所有 required 属性及常用属性。
  • 除使用示例章节外，不在 Markdown 代码围栏中包裹代码；用文字和表格描述代码行为、方法签名和属性类型。
  • 属性始终使用 Markdown 表格而非项目符号列表。
  • 遵循项目约定：从项目文档或代码模式推断并尊重 QML 开发约定。
  • 生成前先检查是否已有文档：文档写入源文件旁的 doc/ 子目录（如源文件在 src/，文档在 src/doc/；Foo.h 对应 src/doc/Foo.md，main.cpp 对应 src/doc/main.md）。使用 Glob 工具或 ls 命令检查，不先读取源文件。若已有文档，通过 AskUserQuestion 让用户选择：更新现有文档、跳过已有文档的文件、为所有内容重新生成、取消。等待用户选择后再操作。
  • 输入处理：单文件或粘贴代码时只记录该组件，从导入、属性名和结构推断应用上下文；文件夹/项目时遍历目录树找出所有 .qml 文件，并读取 CMakeLists.txt、qmldir 或 C++ 头文件以获取模块结构和注册类型的上下文，为每个组件生成一个 .md；若记录多个文件，另创建 doc/index.md 列出每个组件及一行描述和链接。
  • 准确解析 QML：识别根元素基类型、property <type> <name>: <default>、property alias <name>: <target>、required property、signal <name>(<params>)、function <name>(<params>) { }、readonly property、component <Name> : BaseType { } 内联组件；以 _ 前缀的内部辅助通常为私有，除非明显是公共 API 否则跳过；属性缺少清晰描述时根据名称、类型和使用上下文推断。

使用方式

该技能以技能形式提供，具体安装命令与调用方式暂未提供。使用时，它会先检查目标位置是否已有文档，再根据用户选择读取源文件并生成或更新文档。输出位置为源 QML 文件旁的 doc/ 子目录；仅在记录 2 个或以上组件时创建 doc/index.md。

适用场景

  • 需要为 QML 组件或应用编写 API 参考文档。
  • 需要让新加入代码库的开发者快速理解组件用途与项目结构。
  • 需要为可复用 QML 组件提供最小实例化示例。
  • 需要为整个 QML 项目批量生成组件文档并建立索引。

限制

  • 除使用示例章节外，不在 Markdown 代码围栏中包裹代码。
  • 使用示例仅适用于可复用组件（根类型不是 Window 或 ApplicationWindow 等）。
  • 文档应保持项目无关，不假设代码或所提供上下文中未体现的细节。
  • 保存前需进行质量检查：确认每个属性、信号和函数都已记录；在存在可观察绑定或外部调用处填写组件间交互。
  • 该输出由 AI 协助生成。
  • 具体安装命令、收费与价格信息暂未提供。