如何用doxygen生成"global documentation"

Question

我对如何记录代码以及如何使用 @mainpage、@page、@subpage 和相关标签编写“通用文档”有一定的了解。

我需要包含代码的 requirements/specification 文档。

我的问题是让这种文档（概念上不同于代码文档）接近代码实现功能（即：至少在同一个文件中，有时甚至接近特定 classes/functions/methods）但仍然能够以有序的方式收集它并将其呈现在 @mainpage 之外的 file/class 层次结构中。

我理想情况下需要的是能够在各种源文件中随机放置特定的 @page、@section、@subsection 等，然后能够 @include 它们以特定的顺序进入 @mainpage 或其他一些 @subpage.

如果能够在 class/function 完整文档（当然不是 @brief）和@mainpage.

中链接的“前言”

我需要的全局效果是有一个“规范文档”，其中我详细说明了代码的各个部分需要实现的内容，然后是“正常的 class/function/whatever”文档 doxygen id 非常好在提供。

问题（即：我不知道该怎么做）是我想在源代码中将“规范”和实现放在一起，但在文档中将它们分开，即：

一般说明：简单，这进入 @mainpage
要求：最有可能在源文件的顶部实现它们，我如何在主页中link/include？
规范：紧跟在文件顶部的要求之后或在实施它的 class/function 附近的某处；同样在这里，我不知道如何在“前言”中 link/include 又名：@mainpage.
普通代码文档：我唯一不知道的是如何在 class/function 描述中包含已用于 (2) 和 (3) 的相同“文档片段”。

这可能吗？

如果是，最佳做法是什么？

注意：我可以为每个“文档片段”使用一个单独的文件，然后 @include 将其放在正确的位置来获得效果，但这会失败整个目的是将 Requirements/Specification/code 放在一起，同时在生成的文档中将它们分成不同的部分。

更新：根据@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
*/

功能文档已正确呈现（即：删除了标记）
OTOH 初始化页面“有些不完整”：


Initialization

    It needs to do a long series of tests to ensure AM can actually work.

就是这样。

显然找到了标签，但实际上只包含第一行。

进一步更新：按照@albert 的回答（已接受）我成功了，但有以下注意事项：

包含的代码段（[AM_init]）必须在标准评论中，而不是 doxygen 中，否则代码段最终会包含两次。
包含的片段不得有前导*（在“标准评论”中很常见）。
包含的评论应该有 HTML 控制（例如：<br/> 用于行终止）因为 Markdown 构造（“双换行”，在上述情况下) 未被识别。

回想起来，我认为 Doxygen \snippet['{'option'}'] <file-name> ( block_id ) 文档地址中的“注释”或多或少包含上述所有内容，但我发现它非常神秘，如果我不仔细研究它们，我将永远无法理解其中的含义.

最后一个很烦人，因为我使用了很多列表和表格，虽然 HTML 语法更强大，但在源代码中编写和阅读也更难。

找到解除此限制的方法将“非常好”。

Answer 1

使用以下代码和当前的 doxygen 版本 (1.9.4 (5d15657a55555e6181a7830a5c723af75e7577e2)) 以及 1.9.1 (ef9b20ac7f8a8621fcfc299f8bd0b80422390f4b) 版本，我得到了很好的结果=]:[=13

bb.h

/// \file

/**
@page __init Initialization
@snippet{doc} CommandHandler.c AM_init
*/

CommandHandler.c

/// \file

/**
 * Initialization function.
 */

/* [AM_init]
   It needs to do a long series of tests to ensure AM can actually work.<br>

   It should also allocate all dynamic memory needed to avoid runtime failures.<br>

   It will be responsibility of system-level daemon to take appropriate action.<br>
   [AM_init]
 */
/**
 * \snippet{doc} this AM_init
 *
 * @param ip_addr
 * @param port
 * @return
 */
static uint32_t AM_init(const char* ip_addr, uint16_t port){}

Doxyfile

EXTRACT_STATIC = YES
EXAMPLE_PATH = .
QUIET = YES

注意：OP 在进一步更新中正确提到有一些事情需要处理：

包含的代码段 ([AM_init]) 必须在标准评论中，而不是 doxygen 中，否则代码段最终会包含两次。
包含的代码段不能有前导 *（在“标准评论”中很常见）。
包含的评论应该有 HTML 控件（例如：
用于行终止）因为 Markdown 结构（“双换行”，在上面的例子中）是 not 已识别。

如何用doxygen生成"global documentation"

How to generate "global documentation" with doxygen

requirements

specifications

doxygen