Documenting enum class values with doxygen

Question

in my project I use enum class a lot and I'm using doxygen as documentation system. I find very difficult to produce documentation of enum classes when multiple enum classes are declared in the same file and they have the same members. For example, the following code is not generating the correct documentation for enum class IMAGE_REPORTING in final HTML output:

namespace mapper
{
  /* CONNECTION RELATED */
  /** @enum mapper::SECURE_WEBSOCKET
   *  \author Michele Adduci
   *  \ingroup Core
   *  @brief is a strongly typed enum class representing the status of websocket connection
   *  @var mapper::SECURE_WEBSOCKET::DISABLED
   *  is coded as std::int8_t of value 0
   *  @var mapper::SECURE_WEBSOCKET::ENABLED
   *  is coded as std::int8_t of value 1
   */
  enum class SECURE_WEBSOCKET : std::int8_t {DISABLED = 0, ENABLED = 1};

  /* IMAGE RELATED */
  /** @enum mapper::IMAGE_REPORTING
   *  \author Michele Adduci
   *  \ingroup Core
   *  @brief is a strongly typed enum class representing the status of image reporting
   *  @var mapper::IMAGE_REPORTING::DISABLED
   *  is coded as std::int8_t of value 0
   *  @var mapper::IMAGE_REPORTING::ENABLED
   *  is coded as std::int8_t of value 1
 */
  enum class IMAGE_REPORTING : std::int8_t {DISABLED = 0, ENABLED = 1};
}

Output:

Any idea of what is the problem?

Solution 1

You can use inline documentation, which works for me:

/** @enum mapper::IMAGE_REPORTING
 *  \author Michele Adduci
 *  \ingroup Core
 *  @brief is a strongly typed enum class representing the status of image reporting
 */
enum class IMAGE_REPORTING : std::int8_t {
  DISABLED = 0, /**< is coded as std::int8_t of value 0 */
  ENABLED = 1   /**< is coded as std::int8_t of value 1 */
}

and similar for the other.

Solution 2

I was having a similar issue with global enums. Some header files generated a link for enums and other header files did not. You must explicitly document the file.

Here is a excerpt from this page int the documentation. http://www.doxygen.nl/manual/docblocks.html#memberdoc

To document a global C function, typedef, enum or preprocessor definition you must first document the file that contains it (usually this will be a header file, because that file contains the information that is exported to other source files).

Attention Let's repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined. In other words, there must at least be a

/*! \file */ 

or a

/** @file */ 

line in this file.