如何记录与 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 的文档将始终位于属性的文档中。

原因是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() 解析结果： 命名空间名称=`' 类名=`小部件` funcType=`int' funcSpec=`' funcName=`大小' funcArgs=`() 常量' funcTempList=`' funcDecl=`int Widget::size' 相关=`' 例外=`' 相关=0 isMemberOf=0 是朋友=0 isFunc=1 1. funcName=`大小' 2. 会员名存在（2名同名会员） 3. 找到成员定义，scope required=`Widget' scope=`Widget' args=`' fileName=/tmp/test/example.cpp 4.类定义Widget找到 5。匹配 `'`() const' className=Widget namespaceName= 6. matchArguments2 = 1的匹配结果

您甚至可以使用另一个非const 变体int size() 来重现它。您最终将得到三个具有相同名称的成员。 Doxygen 目前无法处理同名的属性和函数，并且在这种情况下没有记录 getter。

如果您不需要属性文档，您可以在Doxyfile 中禁用Q_PROPERTY 宏（如documented）：

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

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

Answer 2

正如承诺的那样： 与原代码的不同之处在于文档不是放在实现文件中，而是放在包含文件中。

包含文件：

// example class and documentation
class Widget : public QObject {
  Q_OBJECT
  //! size is the size of our widget
  Q_PROPERTY(int size READ size WRITE setSize NOTIFY sizeChanged)

public:
  //! Set the widget's size to @a new_size.
  Widget(QObject * parent = nullptr) : QObject(parent){}
  //! Returns the widget's size.
  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.
};

实现文件：

void Widget::setSize(int new_size) {
  if(new_size != m_size) {
    m_size = new_size;
    emit sizeChanged(m_size);
  }
}

int Widget::size() const {
  return m_size;
}

doxygen 配置文件的差异（Doxyfile，可能有几个到多个设置为 YES）：

EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
EXTRACT_PACKAGE        = YES
EXTRACT_STATIC         = YES
EXTRACT_LOCAL_METHODS  = YES
EXTRACT_ANON_NSPACES   = YES