使用 Doxygen 记录发送到 MACRO C++ 的函数答案

【问题标题】：Use Doxygen to document a function that is sent to a MACRO C++使用 Doxygen 记录发送到 MACRO C++ 的函数
【发布时间】：2011-12-24 01:45:39
【问题描述】：

最近我们添加了一些代码来在编译时使用 MACROS 标记已弃用的代码。现在 Doxygen 没有正确记录已弃用的功能。

    #if defined(__GNUC__)
    #define DEPRECATED(func) func __attribute__((deprecated)) /**< mark a function as deprecated in gcc. */ 

    #elif defined(_MSC_VER)
    #define DEPRECATED(func) __declspec(deprecated) func /**< mark a function as deprecated in msvc. */
    #endif

请注意，这是本文宏的简化版本，实际的宏会进行编译器版本检查等。

稍后在函数周围使用宏，让编译器知道该函数已被弃用，因此将发出编译器警告。

    /**
     * myMethod() is deprecated.
     */
    DEPRECATED(
        /**
         * @deprecated
         * Description of deprecated function
         * 
         * @param var this is a parameter
         *
         * @return this is returned 
         */
        int myMethod(int var)
    );

问题是 Doxygen 想要显示 DEPRECATED 的文档而不是 myMethod(int var) 的文档。

有谁知道如何让 Doxygen 记录 myMethod 而不是宏 DEPRECATED？

【问题讨论】：

标签： c++ macros doxygen

【解决方案1】：

您应该告诉 doxygen 它必须删除 DEPRECATED 宏。您可以使用配置文件中的以下预处理器选项来执行此操作：

ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = YES
PREDEFINED             = "DEPRECATED(x)=x"

您可以通过使用-d Preprocessor 选项运行doxygen 来调试预处理的结果。当此选项存在时，Doxygen 将在执行预处理后将输入文件转储到输出。

【讨论】：

我实际上找到了相同的解决方案并准备发布它。只是 PREDEFINED 的注释，值应该是“DEPRECATED(x)=x”，没有引号它没有给出正确的结果。您的解决方案中给出的链接也是我找到解决方案的方式。谢谢:)

【解决方案2】：

使用@fn tag 明确指出该块所指的内容。不如隐式连接方便，但更安全。

【讨论】：

这是我尝试的第一件事。如果那行得通，我就不会在这里发帖了。使用@fn标签的问题是Doxygen需要看到函数。
@fn 标签用于将文档与函数分开。它不是这样您就可以记录 Doxygen 认为不存在的功能。我尝试更改 MACRO_EXPANSION 选项，以便 Doxygen 在尝试应用文档之前处理 DEPRICATE 宏。我认为这是正确的方向，但我无法让它发挥作用。