使用 Doxygen 记录 C++ 中的宏函数

Question

如何使用 Doxygen 在 C++ 中记录宏 function，并在我的非恶意代码的文档中引用它？

更具体地说，我在 Message.H 中定义了一些名为“Message”的常规 class，用户可以从中继承以定义自己的消息。 在另一个文件（“MessageHelpers.H”）中，我有一个像这样的疯狂宏：

//! 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);                       

在 Message 的文档中，如果短语“REGISTER_MESSAGE_TYPE”可以自动成为一个链接并指向我的宏文档，我会很高兴。 例如

//! 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();
};

这可能吗？

Answer 1

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

“特殊命令”部分列出了\\def命令 ， “自动链接生成”部分描述了要链接到宏的内容。

使用\\def来记录与声明分开的宏。
使用#MACRO(params)自动链接到所述宏定义。

Answer 2

Doxygen 的文档（特殊命令）提到了\def命令。

例子

/// \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))

笔记：

• \brief如果文档注释写在宏的顶部就足够了。

• 自动链接生成可用于链接到宏定义，如#MY_MACRO(params)或#MIN(x,y)

• 此外，较新的版本支持所有三个注释 styles：

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