CODEWITHSUNDEEP
c++macrosdoxygen
rcv
rcv

Reputation: 6308

Documenting Macro Functions in C++ with Doxygen

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?

Upvotes: 26

Views: 42262

Answers (2)

Guerrero
Guerrero

Reputation: 534

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.

Upvotes: 20

Top-Master
Top-Master

Reputation: 8745

Doxygen's docs (Special Commands) mentions the \def command.

Example

/// \def MIN(x,y)
/// Computes the minimum of \a x and \a y.

/// \def MAX(x,y)
/// Like #MIN(x,y) - but Computes the maximum of \a x and \a y.

/*! 
   \brief Computes the absolute value of its argument \a x.
   \param x input value.
   \returns absolute value of \a x.
*/
#define ABS(x) (((x)>0)?(x):-(x))

#define MIN(x,y) ((x)<(y)?(x):(y))
#define MAX(x,y) ((x)<(y)?(y):(x))

Notes:

  • \brief is enough if doc-comment is written right at top of the macro.

  • Automatic link generation can be used to link to a macro definition, like #MY_MACRO(params) or #MIN(x,y)

  • Also, newer versions support all three comment styles:

    • ///
    • /**
    • /*!

Upvotes: 1

Related Questions