Document enum class values using Doxygen without enabling EXTRACT_ALL

Question

I wasn't able to show documentation for values of enum classes without setting EXTRACT_ALL. The comments for preserve, truncate and append aren't there. The enum itself is documented. If I enable EXTRACT_ALL I get a list.

My code is:

namespace grimoire
{

...

/// @brief Behaviour of function open_for_write for already existing files.
/// @see open_for_write()
enum class OpenMode
{
    preserve = std::ofstream::out,   /// Already existing file aren't opened.
    truncate = std::ofstream::trunc, /// Discard existing contents.
    append   = std::ofstream::app    /// Append to existing contents.
};

...

}

I'm using CMake to run Doxygen with:

#set(DOXYGEN_EXTRACT_ALL YES)
doxygen_add_docs(
    docs
    "${CMAKE_CURRENT_SOURCE_DIR}/include/grimoire"
    "${CMAKE_CURRENT_SOURCE_DIR}/src")

Edit:

It doesn't even work with a classical enum and without explicit values. It looks like it has to do with my settings.

Solved:

I had to add a comment to the enclosing namespace. Doxygen extracted the enum itself and other stuff like functions and classes inside that namespace but not the enum entries.

Doxygen doesn't completely understand C++. It gets stuff wrong sometimes. — Jesper Juhl, May 31 '20 at 17:41

albert · Accepted Answer · 2020-06-01T12:19:44.110

Doxygen does not always pickup an enum, this can be overcome by means of using the \file command. Furthermore you document the enum values after its definition, this means you should not use /// but ///<

So the limited example would looks like:

/// \file


/// @brief Behavior of function open_for_write for already existing files.
/// @see open_for_write()
enum class OpenMode
{
    preserve = std::ofstream::out,   ///< Already existing file aren't opened.
    truncate = std::ofstream::trunc, ///< Discard existing contents.
    append   = std::ofstream::app    ///< Append to existing contents.
};

Edit: Based on the answer from OP, the given solution was not complete as the original problem was embedded in an namespace. To be able to show the enum in that case it is not sufficient to add the \file but it is also necessary the document the namespace. So a more complete example:

/// \file

/// The namespace documentation
namespace NS
{
  /// @brief Behavior of function open_for_write for already existing files.
  /// @see open_for_write()
  enum class OpenMode
  {
      preserve = std::ofstream::out,   ///< Already existing file aren't opened.
      truncate = std::ofstream::trunc, ///< Discard existing contents.
      append   = std::ofstream::app    ///< Append to existing contents.
  };
};

Still no luck with @file and /// – Martin Fehrs May 31 '20 at 17:49 — Martin Fehrs, May 31 '20 at 17:49

Document enum class values using Doxygen without enabling EXTRACT_ALL

1 Answers1