Doxygen——如何将同一文件的.c和.h文档合并？

Question

涉及使用Doxygen处理C代码时，应该在函数原型还是定义中注释？或者两者都需要？

我认为正确的方法是在.h函数原型中使用Doxygen，包括\param、\return和\brief等标签，因为这样可以隐藏实现细节，只向包含我的.h文件的函数公开API；而在.c函数实现中，则需要更多的\details。到目前为止，这也是stackoverflow上的建议。

能否告诉Doxygen将.c和.h文档合并在一起？因为.c实现可以是原型，我甚至不需要.h函数原型，但我希望Doxygen可以将.h中的\param、\return和\brief标签复制到.html和latex的.c实现文档中。目前，在不同位置重复出现函数会令人困惑和痛苦。至少，我希望\param、\return和\brief可以与函数实现一起重新出现。

/iaw

- ivo Welch

Answer 1

如果这是您的标题：

/**
 * @brief Main function
 * 
 * @param argc number of arguments
 * @param argv array of arguments
 * 
 * @return 0
 */
int main(int argc, char* argv[]);

这是您的源代码：

/**
 * @internal
 *
 * This is an internal implementation command.
 * 
 * @endinternal
 */
int main(int argc, char* argv[])
{
    return 0;
}

您的评论将被合并到文档中。 在此示例中，必须在您的配置中启用INTERNAL_DOCS以获得实现注释。 您将在头文件页面上找到合并后的文档。源文件页面仅显示实现命令。

- Jonas Wolf

---

能否合并代码呢？也就是说，我的Doxygen输出只显示一个输出集，首先是简要说明（来自.h），然后是参数（.h），然后是返回值（.h），然后是实现注释（.c），最后是源代码（.c）？几乎强制性的将.h和.c文件分开（以及单遍性需要前向声明）在1978年很有用，但今天的要求只是自我造成的痛苦。 - ivo Welch

@ivoWelch 我不确定我是否理解您的意思。代码（源代码和头文件）结构是正确的。您只是想要一个包含头文件和源代码的输出文件吗？ - Jonas Wolf

当你说“合并代码”时，你是指源代码中的内联文档（例如：///代码中的内联注释）吗？这些内容将会被附加到输出文档块的末尾。 - Nick