CODEWITHSUNDEEP
objective-ccdoxygen
iter
iter

Reputation: 4313

Doxygen generates entries for enums, but not for their members

I have an enum in my .h file like so:

/** \memberof MyClass
  Values for keypress bitmasks for #method and MyClassDelegate#otherMethod */
enum MY_KEYS {
  MY_KEY_1_DOWN,    /**< KEY 1 press */
  MY_KEY_1_UP,      /**< KEY 1 release */
  MY_KEY_2_DOWN,    /**< KEY 2 press */
  MY_KEY_2_UP,      /**< KEY 2 release */
};

Doxygen generates an entry for this enum under "Public Types" as well as "Member Enumeration Documentation" where the detailed descriptions show up. However, it generates no documentation for the members of the enumeration. I want to list the members of my enumerations and comment them, so that my users can know which values to use where they formal type of an argument is this enumeration.

Don't know if it's relevant--this is in Objective-C, hence \memberof MyClass to show up on this class's page.

Upvotes: 3

Views: 1485

Answers (2)

trapperjohn
trapperjohn

Reputation: 49

I stumbled over the same problem (although for a pure C documentation) - unfortunately this seems to be an issue with Doxygen, see the corresponding Bugzilla entry

individual values in enum not documented if the enum is a member of a C class

https://bugzilla.gnome.org/show_bug.cgi?id=762320

or the older related bug:

When @relatesalso is used, Doxygen does not output members of enum.

https://bugzilla.gnome.org/show_bug.cgi?id=609299

Update:

A quick fix which solves this problem (tested in Doxygen 1.8.11):

Edit src/doxygen.cpp and remove (or comment) line 7375 in function addEnumValuesToEnums:

if (!e->name().isEmpty() && (fmn=(*emnsd)[e->name()]))
  // get list of members with the same name as the field
{
  MemberNameIterator fmni(*fmn);
  MemberDef *fmd;
  for (fmni.toFirst(); (fmd=fmni.current()) ; ++fmni)
  {
    /* REMOVED LINE 7375: if (fmd->isEnumValue() && fmd->getOuterScope()==md->getOuterScope()) // in same scope */
    {
      //printf("found enum value with same name %s in scope %s\n",
      //    fmd->name().data(),fmd->getOuterScope()->name().data());
      if (nd && !nd->name().isEmpty() && nd->name().at(0)!='@')
      {

The "outer scope" of the C enum was still set to global, i.e. the block which adds enum member values had not been reached.

Please note that I made just a short check and did not thoroughly test the fix - it might have side-effects....

Upvotes: 1

koi-feeding
koi-feeding

Reputation: 989

Not sure why doxygen doesn't see enum values as inherited by the \memberof command. It doesn't work if you manually set the individual values as members of the enum or class either.

Anyway, the workaround is that if you want the enum to actually appear inside the class, you need to define it within the class interface:

@interface MyClass : NSobject

/**
  Values for keypress bitmasks for #method and MyClassDelegate#otherMethod 
*/
enum MY_KEYS {
  MY_KEY_1_DOWN,    /**< KEY 1 press */
  MY_KEY_1_UP,      /**< KEY 1 release */
  MY_KEY_2_DOWN,    /**< KEY 2 press */
  MY_KEY_2_UP,      /**< KEY 2 release */
};

@end

This actually makes more sense IMO, as there's no guarantee that header files contain related types - it's just expected of good design.

Upvotes: 1

Related Questions