c++ - 正确使用Doxygen

Question

我一直在尝试使用 Doxygen 来记录我的 C++ 项目，但收效甚微:Doxygen 无法识别某些宏，因此整个函数都被误解了，而且大多数时候不会生成文档，即使它们有特殊的注释 block 。恰当的例子:

/**
 * \def      __MYLIB_FUNCTION_ATTRIBUTE(...)
 * \brief    Some brief comment
 * \details  Detailed doc
 * \sa       Some valid references
 */
#define __MYLIB_FUNCTION_ATTRIBUTE(...)    __attribute__(__VA_ARGS__)

/**
 * \def      IN
 * \brief    Tag for input arguments to a function
 * \details  Blah...
 * \sa       OUT
 */
#define IN

/**
 * \def      OUT
 * \brief    Tag for output arguments to a function
 * \details  Blah...
 * \sa       IN
 */
#define OUT

class MyClass {
public:

    /**
     * \fn        MyClass()
     * \brief     Constructor for MyClass
     * \details   Hi!
     */
    __MYLIB_FUNCTION_ATTRIBUTE(__always_inline__)
    MyClass() {
    }

    /**
     * \fn        const char *doNothing(const char *s IN)
     * \brief     A weird function
     * \details   Some very weird doc
     * \param[in] s No good parameter
     */
    const char* __SXC_FUNCTION_ATTRIBUTE(__const__) doNothing(const char *s IN) {
        return s;
    }
};

为上述类生成的文档总是缺少对 doNothing 的描述，并且 IN 被解释为一个函数!我在这里做错了什么吗？

Answer 1

两件事:

1) Doxygen 解析器不会“看到”doNothing 中的“IN”(因为它在预处理阶段被删除)，所以\fn 不应该包含它:const char* doNothing(const char* s)。顺便说一句，这个\fn 不是必需的:如果评论紧接在文档实体之前，Doxygen 会自动关联评论。

2) 我不知道 __SXC_FUNCTION_ATTRIBUTE 扩展成什么，但是，如果它类似于 __MYLIB_FUNCTION_ATTRIBUTE，它可能会混淆 Doxygen。作为解决方法，您可以在 Doxygen 配置文件的 PREDEFINED 部分中将这些宏定义为空，或者在源代码中有条件地定义它们，如下所示:

#ifdef DOXYGEN
// Doxygen does not grok the normal definition of this
#define  __MYLIB_FUNCTION_ATTRIBUTE(...)
#else
#define __MYLIB_FUNCTION_ATTRIBUTE(...)    __attribute__(__VA_ARGS__)
#endif

并将 PREDEFINED = DOXYGEN 放入您的配置文件中。