CODEWITHSUNDEEP
c++qtdoxygen
SteakOverflow
SteakOverflow

Reputation: 2033

How do you document QFlags with doxygen?

I have something like this (example from the QFlags documentation):

public:
//! Enum doc
enum Option {
    NoOptions = 0x0, //! Value doc
    ShowTabs = 0x1,
    ShowAll = 0x2,
};
Q_DECLARE_FLAGS(Options, Option)

Now I can document Option and its values, and they will be displayed nicely by doxygen. But I cannot make doxygen generate anything for Options. In the Qt documentation it looks like this, they add a note at the top and the bottom of the enum's documentation, and they list it as a separate type in the index section.

More importantly, Qt is able to link to the QFlags where it is used as a function parameter (e.g. QObject::findChild()). Doxygen generates the function signature, shows all the parameters, but does not link the flags type. Can I achieve this somehow?

Upvotes: 4

Views: 243

Answers (1)

Ignitor
Ignitor

Reputation: 3075

Thanks to albert's comment, I was able to make the QFlags type appear in the documentation by doing this:

In the Doxyfile:

  • Set ENABLE_PREPROCESSING = YES
  • Set MACRO_EXPANSION = YES
  • Set PREDEFINED += "Q_DECLARE_FLAGS(flagsType,enumType)=typedef QFlags<enumType> flagsType;"
    or if you prefer to have it show up as an enum instead of a typedef:
    PREDEFINED += "Q_DECLARE_FLAGS(flagsType,enumType)=enum flagsType {};"

Then you can document the Q_DECLARE_FLAGS() invocation like normal:

//! Enum doc
enum Option {
    NoOptions = 0x0, //! Value doc
    ShowTabs = 0x1,
    ShowAll = 0x2,
};
//! QFlags type for \ref Option
Q_DECLARE_FLAGS(Options, Option)

Regarding the note on the enum itself like the Qt docs have it:
I don't think it is possible to have this inserted automatically but you can write an alias and then insert that into the documentation of the enum manually like this:

In the Doxyfile:

ALIASES += qFlagsNote{2}="<p>The \1 type is a typedef for QFlags\<\2\>. It stores an OR combination of \2 values.</p>"

In the C++ code:

/*! Enum doc
 * \qFlagsNote{Options,Option}
 */
enum Option {
    NoOptions = 0x0, //! Value doc
    ShowTabs = 0x1,
    ShowAll = 0x2,
};

will produce:

The Options type is a typedef for QFlags<Option>. It stores an OR combination of Option values.

Upvotes: 4

Related Questions