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

Question

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

更具体地说，我有一个名为"Message"的普通类在Message.H文件中定义，用户可以从中继承以定义自己的消息。在另一个文件（"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();
};

这个可能吗？

- rcv

Answer 1

查看http://www.doxygen.nl/manual/index.html。

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

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

- Guerrero

---

这对我不起作用。我尝试从这里的示例http://www.stack.nl/~dimitri/doxygen/autolink.html复制ABS宏，但没有生成文档，并且我的代码中的引用“#ABS（x）”没有链接。我在我的配置文件中一定做错了什么？ - rcv

我不确定这是否是你的问题，但请确保在宏定义的地方文档化文件。尝试使用 /! \file / 或 / @file */，然后查看doxygen是否生成了任何警告。源代码位于 http://www.stack.nl/~dimitri/doxygen/docblocks.html，搜索"global objects"。（编辑 - 斜杠星号字符似乎没有起作用，但它们应该是多行注释标记） - Guerrero

是的，我在每个文件的顶部都有一个 /*! @file filename.h description... */。有趣的是，我的宏定义在 MessageHelpers.H 文档中根本没有显示出来。 - rcv

通过使用Doxygen图形用户界面前端，如果我转到“专家”选项卡，选择“预处理器”主题，并取消选中“启用预处理”，它会停止文档化示例...但是，输出中会出现“警告：无法解析对' ABS（x）'的显式链接请求”。对不起，我不能提供更多帮助。 - Guerrero

啊哈！ENABLE_PREPROCESSING 起了作用，感谢您的帮助。 - rcv

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)

• 此外，新版本支持三种注释格式：

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

- Top-Master