50

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)

4
  • I deleted my answer because it did not apply to the C++11. enum class {}
    – drescherjm
    Dec 6, 2012 at 21:45
  • 1
    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. Feb 4, 2013 at 13:44
  • 1
    (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). Feb 4, 2013 at 13:58
  • 1
    I'm getting weird issues where sometimes they are documented or not. Jun 18, 2013 at 9:40

3 Answers 3

48

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
9
  • With gist.github.com/c9b75f0a41525b2cbaf2 I get 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? Dec 7, 2012 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, 2014 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 here.
    – Masked Man
    Aug 13, 2014 at 16:14
  • 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, 2014 at 15:48
  • 1
    @parvus yes, it's shitty but until now, It's the only way it works probably
    – madduci
    Aug 24, 2016 at 8:17
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.

8
  • 1
    Thanks. I prefer this style too. Put the documentation where you maintain the source not in the header. Dec 4, 2015 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 7, 2016 at 21:35
  • 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 6, 2017 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! Aug 26, 2018 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. Aug 27, 2018 at 1:37
10

The below style works for me:

enum class Foo {
  /**Foo it with A*/
  A,
  /**Foo it with B*/
  B
}
1
  • 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, 2022 at 23:03

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.