时间戳

首页 > 解决方案 > 标记 doxygen 注释并将它们放在单独的文件中/从源/注释块构建文档

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

问题描述

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

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

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

/*!
 * @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 中定义了一个 ALIAS cmditem=\xrefitem cmditems "Commands" "Command overview"并将其用于记录单个项目。Doxygen 为函数额外生成了一个额外的“相关页面”条目，如下所示：

外部参照项输出

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

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

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

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

在这个例子中，我想在一个文件中包含降价注释，看起来像这样（当然，在对上面的行进行一些修改之后）：

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

标签： cdoxygen

解决方案

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

关于 xrefitem 的可能性，这些是格式化的 wit <dl>，在普通段落中<dd>，<dt>就像在相关页面上的段落一样。因此实际上不可能从中创建一个表。

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

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

所以一般来说我们得到 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 添加段落标记）。

推荐阅读