Documenting enum values with doxygen

Question

Given:

namespace Foo {
    class Foo {
    public:
        /// Foo enum, possible ways to foo
        enum class Foo {
            /// Foo it with an A
            A,
            /// Foo it with a B
            B,
            /// Foo it with a C
            C
        }
    }
}

And the default Doxyfile made with doxygen -g, I get this:

generated documentation

How can I get the enum values documented? I tried putting the comment before/after the member, using ///<, etc, to no avail. Might this just be a bug in doxygen? The examples in the docs work. (Clicking on the name of the enum doesn't bring me anywhere)

I deleted my answer because it did not apply to the C++11. enum class {} — drescherjm, Dec 06 '12 at 21:45
Either of the styles in this question or the answers work for me with Doxygen 1.8.2. On the other hand, _none_ of them work on my colleagues's machine, also with Doxygen 1.8.2 -- and with identical inputs fresh from source control. Something spooky is going on here. — hmakholm left over Monica, Feb 04 '13 at 13:44
(Ah, not so spooky at all. Turned out I had both 1.8.2 and 1.8.3.1 installed, 1.8.2 was first in my path, whereas the build script used the full path to the 1.8.3.1 installation). — hmakholm left over Monica, Feb 04 '13 at 13:58
I'm getting weird issues where sometimes they are documented or not. — Matt Clarkson, Jun 18 '13 at 09:40

score 44 · Answer 1 · edited Mar 24 '19 at 14:51

44

With Doxygen 1.8.2, both the following work for me:

Using ///

/// This is an enum class
enum class fooenum {
    FOO, ///< this is foo
    BAR, ///< this is bar
};

Using /*! ... */

/*! This is an enum class */
enum class fooenum {
    FOO, /*!< this is foo */
    BAR, /*!< this is bar */
};

Brief Description Detailed Description

The doxygen changelog says that enum class is supported in Doxygen 1.8.2, so I suspect there may be some minor syntax issue in your commands. Could you please compare your commands with the above two snippets?

New features

Added support for C++11:
strongly typed enums, e.g.:
enum class E

edited Mar 24 '19 at 14:51

albert

8,285
3
19
32

answered Dec 07 '12 at 03:09

Masked Man

1
7
40
80

With https://gist.github.com/c9b75f0a41525b2cbaf2 I get http://i.imgur.com/nvsD2.png. Same result when it's a member of the class. What do you get with that? How does it differ? – ember arlynx Dec 07 '12 at 20:58
2

I'm having a problem with this solution, when I also assign values to the enumerated members. For example: enum class Positions : std::int8_t { UNDEFINED = -1, /*!< has value -1 */ TOPLEFT = 0, /*!< has value 0 */ TOPRIGHT = 1, /*!< has value 1 */ BOTTOMLEFT = 2, /*!< has value 2 */ BOTTOMRIGHT = 3 /*!< has value 3 */ }; In the doxygen output, I get the fields repeated twice. How can be solved it? – madduci Aug 13 '14 at 12:20
@blackibiza I wish I could help you figure this out (I cannot guarantee that I would be able to solve the problem though), but I was a doxygen fanatic long time ago, and have moved on to bigger and better things since then. If I had a working doxygen setup, I would have had a look. Until then your best bet is to ask a new question to get more visibility, and you would hopefully get someone else to look at it. Note also that the creator and lead developer of doxygen is an [active member](http://stackoverflow.com/users/784672/doxygen) here. – Masked Man Aug 13 '14 at 16:14
I've solved my problem. Working around with @enum and \ingroup, I was able to fix it :) – madduci Aug 14 '14 at 07:19
2

Great! Please consider creating a new question and answering it yourself, to help someone else who would stumble upon the problem in future. – Masked Man Aug 14 '14 at 15:48
@blackibiza Can you specify how exactly you solved that issue? I'm struggling with this myself. – parvus Aug 23 '16 at 12:50
@parvus check here http://stackoverflow.com/questions/25302454/documenting-enum-class-values-with-doxygen – madduci Aug 24 '16 at 06:58
@blackibiza Ok, tx. Bummer. It means the actual value of the enumeration has to be repeated in the comment if you want it to be visible in the generated output. Too bad. – parvus Aug 24 '16 at 07:43
1

@parvus yes, it's shitty but until now, It's the only way it works probably – madduci Aug 24 '16 at 08:17

Alexis Wilke · Answer 2 · 2022-11-22T01:29:31.933

12

Note that I personally hate to have header files that go at length (because documenting means writing at least 2 or 3 lines of documentation, not one word so I generally don't have enough with the brief) so I prefer to document in the .cpp file.

To do that you use the \var feature of Doxygen.

So the header comes bare:

namespace Foo {
    class Foo {
    public:
        enum class Foo {
            A,
            B,
            C
        };
    };
}

And the .cpp file has:

namespace Foo {

/** \enum Foo::Foo
 * \brief Foo enum, possible ways to foo
 *
 * All the necessary details about this enumeration.
 */

/** \var Foo::A
 * \brief Foo it with an A
 *
 * When you use A... etc.
 */

/** \var Foo::B
 * \brief Foo it with a B
 *
 * When you use B... etc.
 */

/** \var Foo::C
 * \brief Foo it with a C
 *
 * When you use C... etc.
 */

}

That way, I can really document at length which happens often to me.

As mentioned by Maxim Paperno in a comment, the \var, like \fn and a few other commands, must be on a line by itself. This is probably done this way because the type following that command can be composed of multiple C/C++ keywords and it would be complicated to distinguish those from a message entered by the document writer.

edited Nov 22 '22 at 01:29

answered Aug 11 '14 at 04:20

Alexis Wilke

19,179
10
84
156

1

Thanks. I prefer this style too. Put the documentation where you maintain the source *not* in the header. – Ed of the Mountain Dec 04 '15 at 14:49
2

However, if you are going to distribute the header file for a library that you wrote, your style means that the header file is free of comments. – hmijail Nov 07 '16 at 21:35
@hmijail Yes and you can have your Doxygen HTML files on some (free) website somewhere... So you can include a link in your header file saying: "Docs can be found over there". – Alexis Wilke Jul 05 '17 at 21:21
7

That's an option, but my point is that if you included your Doxygen in the header, then the header is self-documenting, to the point that you might not even need to actually generate the Doxygen docs. That's why I prefer documenting in the header whatever is in it, and document in the implementation the rest. – hmijail Jul 06 '17 at 10:43
4

If you're not going to keep the documentation close to the source, there's no point in using Doxygen imho. You can just use texinfo. The whole point of Doxygen is to keep the documention close to the source, so hopefully the documentation keeps up to date. When someone adds a field to your enum in the header, they will likely forget to add to the documentation which resides in another file! – Jaap Versteegh Aug 26 '18 at 14:49
1

@JaapVersteegh If you pay attention to the Doxygen warnings, you'll see that it tells you about all the things that are not documented. That's how I can make sure to be doc complete. Unfortunate that it can't generate an error, though, that way it would really force devops to write docs for 100% of their code... otherwise the compile would fail. – Alexis Wilke Aug 27 '18 at 01:37
1

One could set `WARN_AS_ERROR` in the configuration file. – albert Jan 17 '20 at 18:59
Just a note because I struggled a bit with the syntax... Doxy docs also show this but do not explain the subtelties. Doxygen is very picky about the `\var` commands and the actual description **must** be on a new line, not inline with the enum name (like, you can do with, say `\param`). Also that the `\var` commands can be in the same comment block with the `\enum` command, in which case the enum names do not need to be fully qualified (just the actual enum names should work). – Maxim Paperno Nov 22 '22 at 01:15

score 10 · Answer 3 · edited Jan 07 '19 at 23:39

10

The below style works for me:

enum class Foo {
  /**Foo it with A*/
  A,
  /**Foo it with B*/
  B
}

edited Jan 07 '19 at 23:39

Michael Mrozek

169,610
28
168
175

answered Dec 07 '12 at 03:38

Ramón J Romero y Vigil

17,373
7
77
125

1

This is the one I use as well. Note that this only works if the description comes *before* the enum value. – BobMorane Dec 16 '22 at 23:03

Documenting enum values with doxygen

3 Answers3

Linked