CODEWITHSUNDEEP
c++enumsdocumentationdoxygenflags
JBentley
JBentley

Reputation: 6260

Documenting enum flags with Doxygen or similar

I've just added Doxygen to my toolset, and whilst I'm comfortable with most of the techniques, I'm a little confused on how I should go about documenting enum flags (also applicable to documentation in general, with or without Doxygen). Given the following class:

class foo
{
   /// @enum  Options
   /// @brief Specifies options for the object. Options are combined using
   ///        the bitwise OR operator e.g. "OPTION1 | OPTION2".
   enum Options
   {
   OPTION1 = 1, //< Option 1 description.
   OPTION2 = 2, //< Option 2 description.
   OPTION3 = 4  //< Option 3 description.
   };

   /// @brief Does something.
   /// @param options  Specifies options.
   void bar(int options) {/* Do something */}
};

How do I go about indicating to the user how to use the options parameter of the bar function? The parameter is of type int, not Options, so there is no direct link between the parameter and the enum. If the parameter was of type Options, then the documentation would link to the description of the enum, which is the behavior I want.

Upvotes: 1

Views: 2000

Answers (2)

David Hammen
David Hammen

Reputation: 33126

Documenting a variable named options with "Specifies options" is not a meaningful comment. The variable name already says what your existing comment says. So make your comment meaningful:

/// @brief Does something.
/// @param options  Specifies options for the object, which must be a bitwise OR
///                 of zero or more of the bit flags in enum foo::Options.
void bar(int options) {/* Do something */}

Upvotes: 1

Pete Becker
Pete Becker

Reputation: 76448

So make the argument type Options. You can write overloaded operators that return Options to handle & and | and any other logical operators that you need.

Upvotes: 2

Related Questions