CODEWITHSUNDEEP
c++qtdoxygen
Tamás Szelei
Tamás Szelei

Reputation: 23961

How to doxygen comment Qt properties?

I would like to attach Doxygen comments to my Q_PROPERTYs.

For example:

song.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);
};

song.cpp

#include "song.h"

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

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

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

How can I tell Doxygen that title is a property in the Qt Meta-Object system and title() and setTitle() are the accessor functions? I would like to achieve a similar output to this.

Upvotes: 11

Views: 6146

Answers (3)

Nathan Osman
Nathan Osman

Reputation: 73275

I have finally found a way to do this.

  • In the source files:

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

  • In the Doxyfile:

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

What I've done is define an alias named "accessors" that will generate a paragraph with the title "Accessors:" followed by the referenced methods.

Here's what it looks like in the documentation:

enter image description here

Tip: if the name of the property is the same as the method for reading the property, you may want to precede the accessor's name in the documentation by a '%' (otherwise the accessor will be displayed as a link that points to itself):

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

Upvotes: 13

user355252
user355252

Reputation:

doxygen supports Qt properties out of the box. Just add a documentation comment above the property declaration, and you will see a "property" in the doxygen output.

Please note, that the accessor functions will be documented separately, if they also have documentation comments. You therefore need to remove documentation comments from these accessor functions, if you want to suppress these in the generated documentation.

Upvotes: 14

chalup
chalup

Reputation: 8516

The doxygen comment in qobject.cpp for objectName property starts with "\property" tag:

/*!
    \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()
*/

Have you tried using it? If it doesn't work out of the box, I'd try to find out how Qt generates it's docs - maybe you need some macros/aliases in doxygen configuration.

Upvotes: 2

Related Questions