如何生成“全球文档”与doxygen

Question

我对如何使用@mainpage，@page，@subpage和相关标签。

我需要包括代码的要求/规范文档。

我的问题是将这种文档（概念上与代码文档不同）保持在代码实现功能附近（即至少在同一文件中，有时甚至是特定类别/函数/方法），但仍然可以在有序的时尚并在@mainpage，外部文件/类层次结构中呈现。

理想情况下，我需要的是能够放置特定@page，@section，@subsection等然后，可以@include以@mainpage或其他其他@subpage 中的特定顺序。

甚至最好是能够在类/函数中包含相同 @mainpage。

我需要拥有的全局效果是要拥有一个“规范文档”，其中我详细介绍了代码的各个部分才能实现的内容，然后详细介绍了“正常类/函数/任何“任何”文档doxygen doxygen ID非常擅长提供。

我想在源中保留“规范”并将其放在源中，但是在文档中将它们分开，即：

1. 一般说明：简单，这将变成> @mainpage
2. 要求：最有可能在实现它们的源文件的顶部，如何链接/包括在主页中？
3. 规范：在文件顶部要求之后或实施该类别/功能附近的某个地方；另外，在这里，我不知道如何链接/包含在“前面”中：@mainpage。
4. 普通代码文档：我不知道的只有在类/功能中包括在（2）和（3）中使用相同的“ DOC摘要”。

这可能吗？

如果是这样，最好的做法是什么？

Note ：我可以使用每个“ DOC代码”的单独文件获得效果将需求/规格/代码放在一起，同时将它们分开的文档中的不同部分分开。

更新：按照@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答案（接受）我取得了成功，但是以下警告：

• 包括smippet（[am_init]）必须必须标准评论，而不是doxygen，否则摘要最终包括两次。
• 包含的smippet 必须不能具有领先的*（在“标准注释”中很常见。
• 随附的注释应该具有HTML控件（例如：＆lt 我认为doxygen 中的“注释”。

; br/＆gt; 用于线路终止），因为在上述情况下，标记构造（在上述情况下为“双重新线”）在回顾中 \ spippet ['{'opote'}']＆lt; file-name＆gt;（block_id）文档地址，以上所有内容鼻子被摩擦到最后一个非常烦人的，

而HTML语法更加强大，但写作也很难。

因为我使用了很多列表和桌子， 会“非常好”。

Answer 1

使用以下代码和当前的doxygen版本（1.9.4（5D15657A55555E6181A7830A5C723AF75E757E2）），但也具有1.9.1

>

/// \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

注意：在进一步更新中正确提及的是，有一些事情要照顾：

• 随附的smippet（[am_init]）必须在标准评论中，不是Doxygen，否则片段最终包括两次。
• 包含的摘要一定不能具有领先 *（在“标准评论”中很常见。
• 随附的注释应具有HTML控件（例如：
  用于线终止），因为Markdown构造（在上面的情况下为“ Double Newline”）是 认可。