c++ - 如何记录与 Q_PROPERTY 同名的访问器函数？

Question

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 的 文档。上面的代码就像

//! @property size
//! @brief Returns the widget's size.
int Widget::size() const {
  return m_size;
}

被使用了。 @fn Widget::size()const 和任何其他 doxygen 特殊命令似乎都无济于事:size() 生成的文档保持为空并最终出现在 size(属性)文档。

这是一个错误，还是我遗漏了什么？

Answer 1

这是一个 known bug或者更确切地说是未实现的功能。从今天开始，如果属性和 getter 具有相同的名称，则不可能记录它们。 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=-1findMember(root=0x197efe0,funcDecl=`int Widget::size() const ',related=`',overload=0,isFunc=1 mGrpId=-1 tArgList=(nil) (#=0) spec=0 lang=200findMember() 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=11. 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.cpp4. class definition Widget found5. matching `'`() const' className=Widget namespaceName=6. match results of matchArguments2 = 1

You can even reproduce this with another non-const variant int size(). You will end up with three members that have the same name. Doxygen cannot handle properties and functions with the same name at the moment and does not document the getters in this case.

If you don't need the property documentation, you can disable the Q_PROPERTY macro in your Doxyfile (as documented):

ENABLE_PREPROCESSING  = YES
MACRO_EXPANSION       = YES
PREDEFINED            = Q_PROPERTY(x)= 

这样词法分析器就不会扫描Q_PROPERTY。