外部文件中的扩展模块/组文档

Question

我有一个可能很简单的问题，但我的 Google-Fu 没有产生任何结果。

我有一个这样的 doxygen 记录的头文件：

/**
 * @file filename.h
 *
 * @date today
 * @author me
 *
 *  @defgroup mygroup grouptitle
 *  @brief my nice functions
 *
 *  Here is a medium sized description, 4-5 lines, which outline the
 *  functions and the way these functions work together, what is init,
 *  what is the main function of this module and maybe additional
 *  information on used hardware (as it is mainly embedded software).
 *
 *  Here starts another description block, typical length around 20-50
 *  lines. Detailed Hardware description, code snippets as examples and
 *  so on. I want to remove this section from the header file and
 *  replace it by something like
 *  /special_doyxgen_command_to_insert extended_doc_mygroup.md
 *
 *  \addtogroup mygroup
 *  @{
 */

here are function definitions, enums, defines and what else

/** @} */

我不知道这是否可行，但我有一个额外的 mygroup.md，其中给出了一些示例并显示了一般用法。根据文件的不同，它有 10 到 50 行，主要是 1 或 2 个代码示例。

过去我在头文件/源文件中插入了示例，但我不喜欢这种方法，所以我创建了一个 markdown 文件并通过 doxygen ref 函数链接到这个文件。 我想要的是在我的组文档（HTML 和 Latex 文件）的“详细描述”部分中插入 .md 竞争的“插入”标签。

是否有这样的命令（或一组命令来获取我的方法？）

Answer 1

有许多命令可以在您的文档中包含外部代码示例。查看配置标签EXAMPLE_PATH 和特殊命令@include 和@snippet。您可以创建一个名为“examples”的目录，将示例文件放入其中并通过在EXAMPLE_PATH 标签中输入此目录来告诉 doxygen：

EXAMPLE_PATH  = ./examples

然后创建一些示例文件，例如：examples_1.c

/// [Example1]
/// Here some more text to explain the example which is not shown by the \@snippet command.

// But normal comments are shown as a part of the code
for(;;)
{
     doSomething();
}
/// [Example1]

/// [Example2]
while(1)
{
    doSomething2();
}
/// [Example2]

现在您可以在您的组文档中使用@snippet 命令添加这些代码 sn-ps：

/**
* @defgroup ...
* ...
* @snippet examples_1.c Example1
* ...
* @snippet examples_1.c Example2
*/

您也可以包含整个源文件的代码：

/**
* ...
* @include examples_2.c 
* ...
*/

您应该注意的另一个方法是@copydoc 和@copydetails 命令的用法。

希望这能回答你的问题。