26

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?

rcv
  • 6,078
  • 9
  • 43
  • 63

2 Answers2

20

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.

Top-Master
  • 7,611
  • 5
  • 39
  • 71
Guerrero
  • 534
  • 4
  • 11
  • 1
    This doesn't work for me.. I tried copying the ABS macro from the example here http://www.stack.nl/~dimitri/doxygen/autolink.html but no documentation was generated, and the reference in my code "#ABS(x)" did not link. I must be doing something wrong in my config file? – rcv Dec 28 '10 at 00:10
  • 1
    I don't know if this is your issue, but make sure that you document the file somewhere the macro is defined. Try either /*! \file */ or /** @file */, and see if doxygen has generated any warnings. Source is http://www.stack.nl/~dimitri/doxygen/docblocks.html searching for "global objects". (edit - the slash star characters didn't appear to work, but they should be multi-line comment markers) – Guerrero Dec 28 '10 at 01:09
  • Yup, I have a /*! @file filename.h description... */ at the top of every file.. It's interesting that my macro definition doesn't show up in my MessageHelpers.H documentation at all. – rcv Dec 28 '10 at 02:03
  • 3
    Using the Doxygen GUI frontend, if I goto the "Expert" tab, the "Preprocessor" topic, and uncheck ENABLE_PREPROCESSING, it stops documenting the sample... But then I get "Warning: explicit link request to 'ABS(x)' could not be resolved" in the output. I'm sorry I couldn't be of more help. – Guerrero Dec 28 '10 at 02:40
  • 1
    Ah ha! The ENABLE_PREPROCESSING did the trick, thanks for the help. – rcv Dec 28 '10 at 03:16
1

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:

    • ///
    • /**
    • /*!
Top-Master
  • 7,611
  • 5
  • 39
  • 71