如何 doxygen 评论 Qt 属性？

Question

我想将 Doxygen cmets 附加到我的 Q_PROPERTY。

例如：

歌曲.h

class Song : public QObject
{
    Q_OBJECT

private:
    Q_PROPERTY(QString title READ title WRITE setTitle);
    QString _title;

public:
    QString title() const;
    void setTitle(const QString& value);
};

歌曲.cpp

#include "song.h"

Song::Song(QObject *parent) :
    QObject(parent)
{
}

QString Song::title() const { return _title; }

void Song::setTitle(const QString &value) { _title = value; }

如何告诉 Doxygen title 是 Qt 元对象系统中的一个属性，而 title() 和 setTitle() 是访问器函数？我想实现与this 类似的输出。

Answer 1

我终于找到了办法。

• 在源文件中：

  /**
   * @brief The name of the user.
   * @accessors name(), setName()
   */
  Q_PROPERTY(QString name READ name WRITE setName)
  

• 在Doxyfile：

  ALIASES = "accessors=\par Accessors:\n"
  

我所做的是定义名为“accessors”的an alias，它将生成一个标题为“Accessors:”的段落，后跟引用的方法。

这是文档中的内容：

---

提示：如果属性的名称与读取属性的方法相同，您可能需要在文档中的访问器名称前加上“%”（否则访问器将显示为指向自身的链接）：

/**
 * ...
 * @accessors %name(), setName()
 * ...
 */

Answer 2

doxygen 支持开箱即用的 Qt 属性。只需在属性声明上方添加一个文档注释，您就会在 doxygen 输出中看到一个“属性”。

请注意，访问器函数将单独记录，如果它们也有文档 cmets。因此，如果您想在生成的文档中抑制这些访问函数，则需要从这些访问器函数中删除文档 cmets。

Answer 3

qobject.cpp 中 objectName 属性的 doxygen 注释以“\property”标签开头：

/*!
    \property QObject::objectName

    \brief the name of this object

    You can find an object by name (and type) using findChild(). You can
    find a set of objects with findChildren().

    \snippet doc/src/snippets/code/src_corelib_kernel_qobject.cpp 5

    By default, this property contains an empty string.

    \sa metaObject(), QMetaObject::className()
*/

您是否尝试过使用它？如果它不能开箱即用，我会尝试找出 Qt 是如何生成它的文档的——也许你需要一些 doxygen 配置中的宏/别名。