扩展 Module/Group 外部文件中的文档

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 个代码示例。

过去我在 header/sourcefiles 中插入了示例，但我不喜欢这种方法，所以我创建了一个 markdown 文件并通过 doxygen ref 函数链接到它。我想要的是一个 'insert' 标签，它在我的组文档（HTML 和 Latex 文件）的 'Detailed Description' 部分插入 .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 命令在您的组文档中添加这些代码片段：

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

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

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

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

希望这能回答您的问题。

扩展 Module/Group 外部文件中的文档

Extended Module/Group Documentation in external file

c

doxygen