如何使用Doxygen记录宏生成的类？

Question

我使用宏以下列方式生成类:

generator.h:

class CLASS_NAME : public parent
{
    //generate variables with names given by CLASS_VARIABLES using complicated
    //Boost.Preprocessor stuff.
};

#undef CLASS_NAME
#undef CLASS_VARIABLES

myclass.h:

#define CLASS_NAME MyClass
#define CLASS_VARIABLES (a, b, c, x, y, z)
#include "generator.h"

实际的类更复杂,并使用各种Boost.Preprocessor宏.有没有办法通过向generator.h添加注释来自动记录使用Doxygen生成的类,或者生成带文档的示例类？我尝试过启用ENABLE_PREPROCESSING和MACRO_EXPANSION,但这似乎不够.

Answer 1

在我写这篇文章的时候，doxygen将执行完整的文件包含，只要满足几个条件。来自doxygen 内部文档：

...预处理器在遇到 #include 时进行解析，但实际上并不包含代码（除了在 { ... } 块中找到的 #include）

我通过实验发现的另一个未记录但直观的先决条件是，#include 所在的任何 {...} 块本身都必须被记录下来。例如，使用Boost.Preprocessor在以下测试文件上运行 doxygen将为 structs FOO::A、FOO::B、 和生成条目FOO::C，前提MACRO_EXPANSION是在配置文件中启用，所需的提取模式设置为“所有实体”，并且 boost 文件夹正确设置INCLUDE_PATH：

#include <boost/preprocessor/iteration/local.hpp>
#include <boost/preprocessor/tuple/elem.hpp>

#define STRUCTS (A, B, C)

namespace FOO {
    #define BOOST_PP_LOCAL_MACRO(n) struct BOOST_PP_TUPLE_ELEM(3,n, STRUCTS) {};
    #define BOOST_PP_LOCAL_LIMITS (0,2)
    #include BOOST_PP_LOCAL_ITERATE()
}

但是，删除FOO以将结构放置在匿名命名空间中将导致没有文档。所以，如果你能忍受#include "generator.h"在一个显式的命名空间内，它就会起作用。

Answer 2

这是行不通的。Doxygen 预处理器并不真正执行完整的文件包含（它仅在包含的文件中查找宏定义；否则，ENABLE_PREPROCESSING 指令将完全无用！）。所以#include "generator.h"没有效果。

如果您将#include指令实际替换为包含文件的内容，它将起作用。（我知道不是很有用）。

另一种方法是修改您的文件，如下所示：

生成器.h：

#define DEFCLASS class CLASS_NAME : public parent \
{ \
   ... whatever ... \
};

myclass.h：

#define CLASS_NAME MyClass
#define CLASS_VARIABLES (a, b, c, x, y, z)
#include "generator.h"
DEFCLASS

但如果您在每个源文件中多次使用 DEFCLASS，则此方法将不起作用（可能是 Doxygen 的错误/缺陷）。