Generating enum class Documentation with Doxygen

Doxygen is the defacto standard for generating API documentation in C++. Documentation on how to comment code to produce your API documentation is generally good, but there are places where the Doxygen documentation is somewhat lacking. I recently ran across one of these cases: documenting enum class enumerations. There is no mention whatsoever in the Doxygen documentation of how to document enum class. enum is documented, but following the methods shown for it may cause problems.

To illustrate the problems, look at the following code. Note that Enum2, Enum2, and Enum3 all have a value called e2.

namespace ns {
    struct A
    {
        enum class Enum1 {
            e1,
            e2
        };

        enum class Enum2 {
            e3,
            e2
        };

        enum class Enum3 {
            e2
        }
    };
}

Trying the following:

/// This is Enum1
/// \var e1
/// This is Enum1::e1
/// \var e2
/// This is Enum1::e2
enum class Enum1 {
    e1,
    e2
};

and so forth, produces this output:

enum1

You should note three things:

  1. The documentation for  Enum1::e2, Enum2::e2, and Enum3::e2 are all placed together in the documentation for Enum1::e2.
  2. There is no documentation for Enum3. This is because there is only one enumeration value, Enum3::e2, which is included in the documentation for Enum1::e2.
  3. The descriptions for Enum1, Enum2, and Enum3 are not placed as descriptions for the enumerations, but rather as part of the documentation for the values.

The only correct way to document enumeration class values is to not use the special \var command, but to place the documentation inline as follows:

enum class Enum2 {
    e3,     ///< This is Enum2::e3
    e2      ///< This is Enum2::e2
}

If you need multiple lines to describe a value, start the documentation on the line below the value, not on the same line. If you start on the same line as the value, that line will be placed last in the description for the value. This will be shown in the final example.

The special command, \enum, should only be used if the description of the enum class is placed after the enum class is defined. To switch back to placing the description before the next enum class, you must use the \enum special command before that description as well.

Here is an example that shows each of these changes. Firstly, note that there is a description for each enumeration. Secondly, each value is correctly described, except Enum2::e3, where the second line of the description in the header file is placed first in the documentation. This is because the first line of the description was placed on the same line as the enumeration value.

namespace ns {
    /// Description of struct A
    struct A
    {
        /// This is enumeration Enum1
        enum class Enum1 {
            e1,     ///< This is Enum1::e1
            e2      ///< This is Enum1::e2
        };

        enum class Enum2 {
            e3,     ///< This is Enum2::e3.
            ///< Second line of Enum2::e3
            e2
            ///< First line of Enum2::e2 description.
            ///< Second line of Enum2::e2 description
            ///<
            ///< Third line of Enum2::e2 description
        };
        /// \enum Enum2
        /// This is enumeration Enum2

        /// \enum Enum3
        /// This is enumeration Enum3
.        enum class Enum3 {
            e2      ///< This is Enum3::e2
        };
    };
}

enum2

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s