标记 doxygen 注释并将它们放在单独的文件中/从源/注释块构建文档答案

【问题标题】：Mark doxygen comments and put them in a separate file / build documentation from source/comment blocks标记 doxygen 注释并将它们放在单独的文件中/从源/注释块构建文档
【发布时间】：2021-03-08 08:18:55
【问题描述】：

我的问题不容易用简短的说明来描述，所以我尝试更详细地解释它：

我想从源代码中的 cmets 生成文档。我最喜欢的方式是单独生成包含收集的评论块的降价文件。

这是我想做的示例源代码：

/*!
 * @brief   Command management
 */
void DoCommands()
{
    // \HTML Variant
    /*!
    This part is a html sequence \n
    Here \b<a table> will appear \n
    <table>
    <tr><th> Command </th> <th> Function </th></tr>
    <tr><td> ? </td><td> Dummy </td></tr>
    */
    switch (Cmd)
    {
        /*!
        <tr><td>v </td><td>Get version </td></tr>
        */
        case 'v': SendVersion(); break;
        /*!
        <tr><td>q </td><td> Quit program </td></tr>
        </table>
        */
        case 'q': Quit(); break;
    }

    // XRefItem Variant
    /*!
    This part is a xrefitem sequence \n
    Here \b<a table> will appear \n
    \cmditem Command, Function
    \cmditem ?, Dummy
    */
    switch (Cmd)
    {
        /*!
        \cmditem v, Get Version
        */
        case 'v': SendVersion(); break;
        /*!
        \cmditem q,  Quit program
        */
        case 'q': Quit(); break;
    }


    // Markdown Variant
    /*!
    This part is a markdown sequence \n
    Here **a table** will appear \n
    Command | Function \n
    ----|-------
    ? | Dummy
    */
    switch (Cmd)
    {
        /*!
        v | Get Version
        */
        case 'v': SendVersion(); break;
        /*!
        q | Quit program
        */
        case 'q': Quit(); break;
    }
}

该函数处理不同的命令，我想将命令的描述放入案例中，以便将源代码和文档放在一个地方。

如您所见，我尝试了多种可能性来使用 Doxygen 收集这些信息。第一个带有 html 标签的解决方案效果还不错。生成的 html 如下所示：

但它并不完美。由于表格是在多个块上构建的，因此在“Dummy”和“Get version”之后添加了一个额外的换行符，因此它们与“？”不一致。和“v”。

我的下一个尝试是使用 \xrefitem。我在 Doxygen 中定义了一个别名 cmditem=\xrefitem cmditems "Commands" "Command overview" 并将其用于记录单个项目。 Doxygen 为函数额外生成了一个额外的“相关页面”条目，如下所示：

问题是，我不知道如何将这个格式设置为漂亮的表格...

最后我尝试用 markdown 语法编写表格，但这仅适用于表格的第一个条目。单独注释块中的第二个条目未添加到表中。

有谁知道如何获得格式精美的文档，其中包含针对不同命令的单独注释块？

我需要将命令文档提供给客户。他不需要关于代码和函数的所有其他东西。所以“蛋糕上的樱桃”应该是一个指令/命令，它告诉 doxygen “按原样”获取注释块并将其放入/附加到单独的文件中。

在本例中，我希望将降价 cmets 放在一个文件中，该文件可能如下所示（当然，在对上述行稍作修改后）：

This part is a markdown sequence  
Here **a table** will appear  
| Command | Function |
|----|-------|
|? | Dummy|
|v | Get Version|
|q | Quit program|

【问题讨论】：

你使用的是哪个版本的 doxygen？
我使用的是 Doxygen 1.8.20 版

标签： c doxygen

【解决方案1】：

你是对的，每个评论块都是一个单独的段落，因此 Doxygen 在表格中插入 <p> ... </p> 这会导致多余的行。

生成的html代码如下：

</p><table class="doxtable">
<tr>
<th>Command  </th><th>Function  </th></tr>
<tr valign="top">
<td>? </td><td><p class="starttd">Dummy </p>
<p class="endtd"></p>
</td></tr>
<tr valign="top">
<td>v </td><td><p class="starttd">Get version </p>
<p class="endtd"></p>
</td></tr>
<tr valign="top">
<td>q </td><td><p class="starttd">Quit program </p>
<p class="endtd"></p>
</td></tr>
</table>

您的解决方法有助于获得表格条目的统一布局：

谢谢！

【讨论】：

【解决方案2】：

要理解这种行为，必须知道不同的注释块不是直接相互附加的，而是每个块被视为不同的段落，因此降价表条目有空行，从而破坏了表格.

关于外部物品的可能性，这些在普通段落中被格式化为<dl>、<dd> 和<dt>，就像相关页面上的段落一样。因此实际上不可能用它创建一个表。

关于 HTML 解决方案。 ? 和 v 行有一个额外的换行确实有点奇怪，这也是由于额外的新行（虽然对我来说有点奇怪，因为新行是在封闭的行之后（这已经是在 doxygen 代码中调查为什么会发生这种情况）。为了在这里获得更好的输出，我建议

将</table> 从开关中取出，所以q 也有额外的一行
在<tr>标签中使用属性valign="top"

所以通常我们得到 HTML 部分：

/*!
 * @brief   Command management
 */
void DoCommands()
{
    // \HTML Variant
    /*!
    This part is a html sequence \n
    Here \b<a table> will appear \n
    <table>
    <tr valign="top"><th> Command </th> <th> Function </th></tr>
    <tr valign="top"><td> ? </td><td> Dummy </td></tr>
    */
    switch (Cmd)
    {
        /*!
        <tr valign="top"><td>v </td><td>Get version </td></tr>
        */
        case 'v': SendVersion(); break;
        /*!
        <tr valign="top"><td>q </td><td> Quit program </td></tr>
        */
        case 'q': Quit(); break;
    }
        /*!
        </table>
        */
}

我认为这张桌子看起来确实好一些，例如? 不再位于单元格的中间，额外的空行不容易删除。对于了解 css 的人，可以使用以下设置创建 HTML_EXTRA_STYLESHEET，例如：

p.endtd {
        margin-bottom: -14px;
}

但这会影响所有表格，其中在单元格内使用段落标记（doxygen 添加段落标记）。

【讨论】：