如何通过在C文件中记录#defines来保持doxygen？

Question

我在标题中有#define值，我当然希望Doxygen记录，但我在C文件中有其他我认为是静态常量，我不希望Doxygen记录它们。 像傻瓜一样简单愚蠢的东西

#define NUMBER_OF(a) (sizeof((a))/sizeof((a)[0]))
#define MSTR(e) #e

如何让Doxygen不将这些#define放入它创建的文档中？ 我试过用@internal标记它，但似乎没有帮助。

关于Doxygen和#define一个有点相关的问题，我怎样才能得到：

#define SOME_CONSTANT 1234 /**< An explanation */

在输出中输入“SOME_CONSTANT”和“An explain”而不是“1234”？

Answer 1

无需使用\\cond和\\endcond命令。 您只需使用\\hideinitializer命令即可隐藏初始化程序：

#define SOME_CONSTANT 1234 /**< An explanation @hideinitializer */

关于第一个问题，您可以设置HIDE_UNDOC_MEMBERS = YES并且只有具有Doxygen文档块的宏将显示在输出中。

Answer 2

您可以在doxyfile中设置MAX_INITIALIZER_LINES = 0以隐藏定义的值。

Answer 3

您可以使用\\cond ... \\endcond标记从Doxygen解析中排除代码的任何部分。

编辑：一些相关问题：

• Doxygen如何排除C ++类？
• 从doxygen文档中排除一些类

Answer 4

您只想记录.h文件中声明的内容。 我假设您在.c文件中将所有静态函数和变量声明为static 。 所有剩余的都在.h相应的文件中声明。 这些是您的“公共”成员。

在这种情况下我喜欢做什么，而且我相信doxygen更适合用这种方式：

• 在您的Doxyfile ，设置EXTRACT_ALL = NO并将.h文件所在的目录添加到INPUT
• 将/** \\file */添加到所有.h文件（但不是.c文件）。

这将仅索引.h文件中包含的内容。 您仍然可以将包含.c文件的目录添加到Doxyfile INPUT中，并且将扫描它们以获取“公共”成员的其他文档...

Answer 5

毫无疑问，它仍然会显得嘈杂和不自然，但要解决您的其他问题，请尝试：

/** An explanation */
#define SOME_CONSTANT /** @cond */ 1234 /** @endcond */

Answer 6

我通过将文档从.c文件移动到.h文件解决了这个问题。 然后只在.h文件上运行doxygen。

然后我要记录的项目（'公共'项目）本质上是doxygen选择的。

因为我之前已经小心地将.h文件中的'public'项目和.c文件中的'private'项目放在一起，这非常有效。

当我注意到doxygen正在拉入包含时，我想到了这种技术。 让我感到震惊的是，如果我还要移动调用模块需要使用我的模块的包含子集，那么该列表也将被记录。

这种技术还有一个额外的好处：我可以在更新文档时将文档放在一个终端窗口中，将源放在不同的终端窗口中。

Answer 7

有时你可能有一个你想要记录的定义，但是想要doxygen以不同方式对待它（或者甚至完全忽略它以避免解析错误）。 为此，您可以在doxygen中定义#define，而不是在源代码中定义.define。

示例：某些编译器允许与特定段的变量链接，即：

const int myvar @ "segment_of_myvar_in_memory"=123;

=> doxygen会将“segment_of_myvar_in_memory”部分解析为不需要的变量名。 我们可以使用它的定义：

#define __link_to_segment(name) @ name
const int myvar __link_to_segment("segment_of_myvar_in_memory")=123;

如果Preprocessing处于活动状态，Doxygen现在将我们的变量解释为函数，因为类似于函数的定义使用括号。但是如果我们在Doxyfile中重新定义我们的定义，行为会改变：

PREDEFINED = __link_to_segment(a)=

现在变量被正确解析为变量 - 前面的所有类型或关键字都正确显示为关键字。

一个不错的方面：如果您在代码中使用2个不同的IDE（一个IDE用于编译和调试，一个用于编辑），您还会发现某些IDE（即Eclipse）在使用@“segment name”解析变量时遇到问题。 使用上面的方法，您也可以在那里重新定义__link_to_segment（名称）：

#define __link_to_segment(name)

即Eclipse将正确显示和解析变量，而“编译和调试”IDE仍然可以将变量链接到其段名。