Question

How do I document a macro function in C++ using Doxygen, and refer to it in the documentation of my non-Evil code?

More specifically, I have some regular class called “Message” defined in Message.H that users can inherit from to define their own messages. In another file (“MessageHelpers.H”) I have a crazy macro like this:

//! Users must call this macro to register their messages...
/*! 
   ...lest they be forced to type all sorts of boring and 
   error-prone boiler plate code. 
   blah blah blah... More specific documentation and explanation...
*/
#define REGISTER_MESSAGE_TYPE(MSGTYPE) \
 do_some(MSGTYPE);                     \
 seriously();                          \
 crazy_stuff(MSGTYPE);                       

In the documentation for Message, I would love it if the phrase “REGISTER_MESSAGE_TYPE” could automatically become a link and point to my documentation for the macro. E.g.

//! A cool message class
/*! 
   Users can inherit from this class to create their own cool messages.
   Just be sure to call REGISTER_MESSAGE_TYPE after your class definition!
*/
class Message
{
  virtual void doSomeStuff();
};

Is this possible?

Answer 1

See http://www.doxygen.nl/manual/index.html

The section "Special Commands" lists the \def command, and the section "Automatic link generation" describes what you want to link to the macro.

Use \def to document a macro separate from the declaration.
Use #MACRO(params) to auto-link to said macro definition.