TL; DR：如何为与Q_PROPERTY声明的属性同名的访问器生成doxygen文档？
Qt的property system使得可以在给定属性上使用Qt的元对象系统：
// example class and documentation
class Widget : public QObject {
Q_OBJECT
Q_PROPERTY(int size READ size WRITE setSize NOTIFY sizeChanged)
public:
Widget(QObject * parent = nullptr) : QObject(parent){}
int size() const;
public slots:
void setSize(int new_size);
signals:
void sizeChanged(int); //!< signals a size change
private:
int m_size = 0; //!< the Widget's size,see #size.
};
如果现在在实现中使用doxygen
//! @property size is the size of our widget
//! @brief Set the widget's size to @a new_size.
void Widget::setSize(int new_size) {
if(new_size != m_size) {
m_size = new_size;
emit sizeChanged(m_size);
}
}
//! @brief Returns the widget's size.
int Widget::size() const {
return m_size;
}
只有setSize的文档才能正确生成. size()的文档被误认为属性的文档.上面的代码就像是一样
//! @property size
//! @brief Returns the widget's size.
int Widget::size() const {
return m_size;
}
被使用了. @fn Widget :: size()const和任何其他doxygen特殊命令似乎都没有帮助：size()生成的文档保持为空并最终在size(property)文档中.
这是一个错误,还是我错过了什么？
解决方法
这是一个
known bug或相当未实现的功能.截至今天,如果属性和吸气剂具有相同的名称,则无法对其进行记录. getter的文档总是会出现在属性的文档中.
原因是doxygen的findmember实现.如果你使用doxygen -d findmembers,你可以看到size(属性)和size()(函数)“匹配”：
findMemberDocumentation(): root->type=`int' root->inside=`' root->name=`Widget::size' root->args=`() const ' section=6000000 root->spec=0 root->mGrpId=-1 findMember(root=0x197efe0,funcDecl=`int Widget::size() const ',related=`',overload=0,isFunc=1 mGrpId=-1 tArgList=(nil) (#=0) spec=0 lang=200 findMember() Parse results: namespaceName=`' className=`Widget` funcType=`int' funcSpec=`' funcName=`size' funcArgs=`() const' funcTempList=`' funcDecl=`int Widget::size' related=`' exceptions=`' isRelated=0 isMemberOf=0 isFriend=0 isFunc=1 1. funcName=`size' 2. member name exists (2 members with this name) 3. member definition found,scope needed=`Widget' scope=`Widget' args=`' fileName=/tmp/test/example.cpp 4. class definition Widget found 5. matching `'`() const' className=Widget namespaceName= 6. match results of matchArguments2 = 1
您甚至可以使用另一个非const变量int size()来重现它.您将最终得到三个具有相同名称的成员. Doxygen目前无法处理具有相同名称的属性和函数,在这种情况下不会记录getter.
如果您不需要属性文档,可以在Doxyfile中禁用Q_PROPERTY宏(如documented)：
ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES PREDEFINED = Q_PROPERTY(x)=
这样,词法分析器将不会扫描Q_PROPERTY.
