我对如何记录代码以及使用@mainpage、@page、@subpage等相关标签编写“通用文档”有相当了解。
我需要将要求/规范文档包含到代码中。
我的问题是如何将这种文档（概念上与代码文档不同）保持靠近实现功能的代码（即：至少在同一文件中，有时甚至靠近特定类/函数/方法），但仍能有序地收集它并在@mainpage或其他@subpage中呈现。
我理想情况下需要的是能够在各种源文件中随机放置特定的@page、@section、@subsection等，然后能够按特定顺序@include它们到@mainpage或某些其他@subpage。
更好的做法是能够在类/函数完整文档（不是@brief）和“前置内容”中包括相同的片段，该片段链接到@mainpage。
我需要的全局效果是有一个“规范文档”，其中详细说明了代码的各个部分需要实现什么，然后是 Doxygen 产生的“常规类/函数/其他”文档。
问题在于我希望将“规范”和实现放在源代码中，并将它们分开记录，即：
- 总体描述：简单，这可以放到
@mainpage中 - 要求：最有可能放在实现它们的源文件顶部，如何链接/包含在主页？
- 规范：放在要求之后的文件顶部或某个接近实现的类/函数位置；同样，在此处我不知道如何链接/包含在“前置内容”中，也就是
@mainpage中。 - 常规代码文档：这里唯一不知道的是如何在类/函数说明中包括已用于（2）和（3）的相同“文档片段”。
这个是否可行？
如果可行，那么最佳实践是什么？
注意：我可以使用单独的文件来处理每个“文档片段”，然后在正确的位置进行@include，但这将背离整个目的，即将要求/规范/代码聚合在一起，同时将它们分开在生成的不同文档部分中。
更新：根据@albert的评论，我尝试了以下操作：
- 在标准的Doxygen注释中添加了标记：
/**
* Initialization function.
*
* [AM_init]
* It needs to do a long series of tests to ensure AM can actually work.
*
* It should also allocate all dynamic memory needed to avoid runtime failures.
*
...
* It will be responsibility of system-level daemon to take appropriate action.
* [AM_init]
*
*
* @param ip_addr
* @param port
* @return
*/
static uint32_t AM_init(const char* ip_addr, uint16_t port) {
...
- 在我所定义的“前置事项”中（除其他事项外）：
/**
@page __init Initialization
@snippet{doc} CommandHandler.c AM_init
*/
- 函数文档已正确渲染（即：标记已被删除）
- 另一方面，初始化页面“有些不完整”：
Initialization
It needs to do a long series of tests to ensure AM can actually work.
就是这样。
显然，标签is被找到了，但实际上只包括了第一行。
进一步更新：根据@albert的回答（已接受），我成功了，但有以下注意点：
- 所包含的片段(
[AM_init])必须是一个标准注释，而不是Doxygen注释，否则片段会被包含两次。 - 所包含的片段不能有前导符号
*（在“标准注释”中非常常见）。 - 所包含的注释应该具有HTML控件（例如：用于行结束的
<br/>），因为Markdown构造（在上面的情况下是“双换行符”）不被识别。
回过头来看看，我认为Doxygen \snippet['{'option'}'] <file-name> ( block_id )文档中的“注意事项”，或多或少地解决了以上问题，但我觉得它很难懂，并且如果没有亲身经历，我永远不可能理解其中的影响。
最后一个问题非常恼人，因为我使用了许多列表和表格，尽管HTML语法更加强大，但写起来和阅读起来也更加困难。
找到一种解决这个限制的方法会是“非常好的”。
\snippet这样的命令吗？ - albert@snippet不是我需要的；据我所知，它是用于在文档中包含一些代码片段，而不是我需要的内容。 “小例子”相当困难，但我会更新OP以澄清。 - ZioByte\snippet命令也有doc选项，因此可以使用\snippet{doc}或\snippetdoc。我认为通过\snippet{doc}选项，你可以实现你想要的功能。 - albert