doxygen - 如果注释被分成几部分，请避免在表格的最后一列中换行

Question

我正在用 doxygen 记录我的 C/C++ 代码。我想在一个表中收集（长）参数列表的文档：表的每一行都应该有一小段代码，以便记录每个参数的处理位置（例如，第一列参数名称，第二列列参数说明/默认值/等）。所以，需要把这张长表的评论分成很多块。

考虑以下文档。第一个表有“中断”，而第二个则没有。

/// \file main.cpp 

/// \brief main function 
int main () { 
  /// <table> 
  /// <tr> <td> 1    <td> 2  

  // some code 

  /// <tr> <td> 3    <td> 4 
  /// </table> 
  /// <table> 
  /// <tr> <td> 1    <td> 2 
  /// <tr> <td> 3    <td> 4 
  /// </table> 
} 

在与此文件（称为main.cpp）相同的目录中，我运行doxygen -g cfg和doxygen cfg. 这会创建（除其他外）一个文件html/main_8cpp.html。doxygen 版本是 1.8.17。

第一个表的输出并不令人满意。拆分表格的注释会导致意外的换行，并随后在最后一列中出现难看的条目。

我尝试手动结束表格的行，</td> </tr>但换行行为保持不变。这种行为可以避免吗？

如果我查看 html 源代码，两个表的输出是不同的。

<p>main function </p>
<table class="doxtable">
<tr>
<td>1 </td><td><p class="starttd">2 <br  />
</p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>3 </td><td>4 </td></tr>
</table>
<table class="doxtable">
<tr>
<td>1 </td><td>2 </td></tr>
<tr>
<td>3 </td><td>4 </td></tr>
</table>

问题是段落<p class="starttd">2 <br /> </p>（<p>标签，而不是<br>）。如果我删除它们，换行符就会消失。

标签： doxygen

Answer 1

有点渴望评论。

第一个想法是问题是由于某些行有尾随空格而引起的，当至少有 2 个尾随空格时，这在降价中被视为额外换行符的指示。查看您的输入（使用 vi 并将其设置为列表模式，因此最后是美元符号）我们看到：

  /// <tr> <td> 1    <td> 2  $

在查看时doxygen -d markdown（为了您的方便，我也使用了 1.8.17），我们看到（摘录）：

======== Markdown =========
---- input -------
<table>
<tr> <td> 1    <td> 2
---- output -----
<table>
<tr> <td> 1    <td> 2
<br>

=========

因此额外的换行符。

当删除行中多余的空格时，我们仍然看到同样的问题（只有<br>行在降价输出中消失了）。同样禁用 Markdown 也无济于事。

这让我们进一步思考，当 doxygen 看到 2 个详细部分时，它会尝试将这两个部分视为单独的段落（这通常很合乎逻辑），尽管在这种情况下它具有您看到的效果。我在 1.8.18 版本和当前主版本（1.8.19 (3​​040df2f0aa29a4207de5b37da1d20e3d27340bb)）中看到了相同的效果。

我认为在不破坏其他代码的情况下可以做很多事情，但这必须进行调查。

作为旁注：对我来说，<table>评论块中的未关闭不会触发警告对我来说有点奇怪，对我来说更奇怪的是开始</table>不会触发警告。

编辑

OP 提出了一个好主意：

虽然答案没有真正的解决方案，但它以某种方式让我找到了可能解决问题的搜索结果。如果我以 结束该块\htmlonly <!--并以 开始下一个块--> \endhtmlonly，则详细信息部分中的“中断”将被注释掉。

必须在上面放一个小便条：

我认为这是一个可行的解决方案，尽管在创建其他输出格式（latex / pdf、rtf、docbook...）时，问题也出现在这些格式中，并且不能放在例如\rtfonly里面\htmlonly