通过 Doxygen 中的宏定义的文档函数答案

【问题标题】：Document functions defined through a macro in Doxygen通过 Doxygen 中的宏定义的文档函数
【发布时间】：2012-05-11 10:58:21
【问题描述】：

我有一个实际上并不存在但通过宏定义的类：

#define DEFCLASS(name,datatype) Class name { \
    public: \
        void clear(); \
        datatype obj; \
    };
DEFMETHOD(StringContainer, const char*)

...

StringContainer foo("hi!");

当然它应该是使用模板实现的，但不是我写的，我无法更改它，而且一个大型代码库依赖它。

现在的问题是，我想在 doxygen 中记录 StringContainer。但是，它不是一个真正存在的类，所以如果我这样做：

/*!
    \class StringContainer
    \brief A string container

    \fn void StringContainer::clear()
    \brief Clears the container
*/

我收到 doxygen 警告：

warning: documented function `StringContainer::clear' was not declared or defined.

并且文档不包含该功能。我知道这有点棘手，但是有什么方法可以强制 doxygen 有“信仰”并为 StringContainer 创建文档，即使它没有在源代码中定义？

解决方案

可以创建假的 .h 文件来让 doxygen 相信一个类存在，同时阻止构建系统包含它。这些文件可以具有 .dox 扩展名。这样，我将创建一个包含类定义和文档的 .dox 文件：

class StringContainer {
public:
    /*! Removes the contents of the container. */
    void clear();
    const char *obj;
};

此文件实际上不会包含在构建系统中，其唯一目的是记录 StringContainer。

【问题讨论】：

标签： c++ documentation doxygen

【解决方案1】：

我不得不为现有的代码库做很多事情，我发现使用“EXPAND_AS_DEFINED”配置选项可以为您解决这个问题。在您的 Doxygen 配置文件中，设置以下内容：

EXPAND_AS_DEFINED = DEFCLASS

只要包含“DEFCLASS”定义的文件是您的 Doxygen 的输入，它就可以工作。（即这不适用于“STDMETHOD”之类的东西，因为您可能不包含将“STDMETHOD”定义为 Doxygen 输入的文件）

我在 VS 2010 中进行了如下尝试，并且能够在没有警告的情况下编译和运行 Doxygen。

示例如下：

Base.h 文件：

#pragma once

#define DEFCLASS(name,datatype) class name { \
    public: \
        name(){} \
        void clear(){}; \
        datatype obj; \
    };

DEFCLASS(StringContainer, const char*)


/*!
    \class StringContainer
    \brief A string container

    \fn void StringContainer::clear()
    \brief Clears the container
*/

Base.cpp 文件：

#include "Base.h"

int main()
{
    StringContainer foo;
    foo.clear();


    return 0;
}

DoxygenTest.doxygen

MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = YES
EXPAND_AS_DEFINED      = DEFCLASS

【讨论】：

【解决方案2】：

如果您在 doxygen 配置 (http://www.star.bnl.gov/public/comp/sofi/doxygen/config.htm) 中将 MACRO_EXPANSION 设置为“yes”，则 doxygen 将“看到”StringContainer。

【讨论】：

谢谢。这使得 doxygen 找到了方法。不幸的是，在给定的示例中，它不会将 datatype 替换为 const char *。

【解决方案3】：

我建议阅读 doxygen 手册的这一部分：http://www.doxygen.org/preprocessing.html。解释如何处理 DECLARE_INTERFACE 和 STDMETHOD 宏的部分与您想要的非常相似。

因此，如果您不想在单独的文件中编写虚拟类，这可以作为替代解决方案。

【讨论】：