如何使用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将为结构FOO::A ， FOO::B和FOO::C生成条目，前提是在配置文件中启用MACRO_EXPANSION ，所需的提取模式为设置为“所有实体”，并在INCLUDE_PATH正确设置boost文件夹：

#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

如何在http://www.doxygen.nl/manual/docblocks.html中的 “其他地方的文档”段落

/*! \class CLASS_NAME
    \brief An auto generated class

    A more detailed class description.
*/

/*! \fn CLASS_NAME::CLASS_NAME()
    \brief Default constuctor
*/

Answer 3

它不会起作用。 Doxygen预处理器并不真正执行完整的文件包含（它只查看包含的文件中的宏定义;否则，ENABLE_PREPROCESSING指令将完全无用！）。 所以#include "generator.h"没有效果。

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

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

generator.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的错误/缺陷），这将无效。

Answer 4

我建议将生成的类放在一个单独的标题中，只记录标题。 在最好的情况下，生成的类更多是实现细节。

另一种选择是脚本。 使用你最喜欢的脚本语言，或者像猎豹这样的东西都不会很糟糕。

我猜你的发电机看起来很简单，可以产生锅炉板或特性等等。

GENERATE_CLASS(Foo);
GENERATE_CLASS(Bar);

这样的东西是相当合理的grep饲料。