QDoc生成QML库文档时如何正确配置继承关系与导入语句

问题1：继承关系不展示解决方案 #

Qt 5.10版本的QDoc解析QML类型继承逻辑，依赖依赖模块的索引文件加载，未加载对应索引时\inherits指令会被静默忽略，修复步骤如下：

• 在qdocconf配置文件中添加依赖模块声明，QDoc会自动加载对应模块的类型索引：

  depends += qtcore qtgui qtquick qtquickcontrols
  

  如果你使用的是QtQuick.Controls 2.x版本，将最后一项改为qtquickcontrols2即可。
• 确认\inherits后跟的类型全限定名正确：继承Qt控件保持QtQuick::Button的写法即可，继承自有库控件需要写成[你的模块名]::[自有控件名]的格式。
• 你当前使用Visual Studio开发，需要确保调用qdoc前已经执行过Qt目录下的qtenv2.bat配置环境变量，否则QDoc会找不到Qt官方模块的索引文件。如果自动加载索引失败，可以手动在qdocconf中指定索引路径：

  indexes += [Qt安装路径]/Docs/Qt-5.10.10/qtquick/qtquick.index \
             [Qt安装路径]/Docs/Qt-5.10.10/qtquickcontrols/qtquickcontrols.index
  

问题2：导入语句展示配置方案 #

\qmlmodule指令不能写在QML文件的注释中，仅能在qdocconf配置或者独立的.qdoc全局说明文件中使用，修复步骤如下：

• 先删除所有QML注释里的\qmlmodule MyModule语句，避免解析报错。
• 在qdocconf配置文件中添加两行全局声明，即可自动为所有该模块下的QML类型生成统一的导入语句：

  module = MyModule
  qmlversion = 1.0
  

• 如果你需要自定义模块的总说明，可以在sourcedirs包含的目录下新建一个index.qdoc文件，内容示例：

  /*!
  \module MyModule
  \title 自定义QML控件库文档
  \brief 包含所有自定义QML控件的使用说明
  */
  

修正后完整配置示例 #

qdocconf配置 #

# 模块全局配置
module = MyModule
qmlversion = 1.0
depends += qtcore qtgui qtquick qtquickcontrols

sourcedirs += ../qml/ ./
imagedirs = .

sources.fileextensions = "*.qml *.qdoc"

outputdir  = ./doc/qml/
outputformats = HTML

HTML.stylesheets = style.css
HTML.headerstyles = "<link rel=\"stylesheet\" type=\"text/css\" href=\"style/style.css\"/>\n"

MyButton.qml注释 #

/*!
\qmltype SolidButton
\inherits QtQuick::Button
\brief 自定义按钮控件，继承自QtQuick标准Button

\section1 示例代码
\qml
SolidButton {
    text: "My Button"
}
\endqml
*/

内容的提问来源于stack exchange，提问作者The friendly stranger