qdoc忽略Qt数据类型，生成文档错误显示int，求解决方案

问题根源 #

qdoc把QVariant、QModelIndex这类Qt标准类型识别成int，本质是没正确关联Qt对应模块的文档配置和头文件索引，找不到这些类型的定义，只能用默认类型占位。

修复步骤 #

1. 精准指定依赖的Qt模块 #

把depends = *改成具体用到的模块，比如你的项目用到QtCore（QVariant、QModelIndex）和QtWidgets（CustomFileSystemModel继承自QFileSystemModel）：

depends = qtcore qtwidgets

宽泛的通配符会让qdoc无法精准加载对应模块的类型定义配置。

2. 添加Qt头文件搜索路径 #

在qdocconf里加上Qt头文件的路径，确保qdoc能找到类型定义：

includepaths += /usr/include/qt5/QtCore /usr/include/qt5/QtWidgets

如果你的Qt安装路径不同，替换成实际路径就行。也可以先设置QTDIR环境变量再运行qdoc：

export QTDIR=/usr/lib/qt5
qdoc your-project.qdocconf

3. 确保代码中正确引入Qt头文件 #

检查你的头文件里有没有包含对应Qt头文件：

#include <QVariant>
#include <QModelIndex>
#include <QFileSystemModel>

qdoc是通过代码里的#include语句关联类型定义的，没包含的话肯定识别不了。

4. 手动加载Qt模块的qdoc配置 #

如果自动加载依赖模块配置失效，直接在你的qdocconf里include对应模块的配置文件：

include(/usr/share/qt5/doc/qtcore/qtcore.qdocconf)
include(/usr/share/qt5/doc/qtwidgets/qtwidgets.qdocconf)

路径不对的话，自己找下系统里qtcore.qdocconf的实际位置。

5. 清理缓存重新生成 #

qdoc会存缓存，旧缓存可能搞出问题，先删干净输出目录再重新生成：

rm -rf ./doc/*
qdoc your-project.qdocconf

验证 #

重新生成后，检查CustomFileSystemModel::data的签名应该正确显示为：

QVariant CustomFileSystemModel::data(const QModelIndex &index, int role) const

内容的提问来源于stack exchange，提问作者Информатично