外部文件

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文件）中插入.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命令。

希望这能回答你的问题。