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

Question

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

考虑以下文档。第一个 table 有一个“中断”，而第二个 none.

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

第一个 table 的输出不太令人满意。拆分 table 的注释会导致意外换行，随后最后一列中的条目外观会很丑。

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

如果我查看 html 来源，两个 table 的输出是不同的。

<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>）。如果我删除它们，换行符就会消失。

Answer 1

评论有点长。

第一个想法是问题是由某些行有尾随空格这一事实引起的，当有至少 2 个尾随空格时，这在 markdown 中被视为额外换行符的指示。查看您的输入（使用 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 (3040df2f0aa29a4207de5b37da1d20e3d27340bb)) 中看到了相同的效果。

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

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

编辑

OP 提出了一个好主意：

While the answer has no real solution, it brought me somehow to search results which might have solved the problem. If I end the block with \htmlonly  \endhtmlonly, the ‘break’ in the details section is commented out.

必须附上一张小纸条：

I think this is a viable solution, though when creating an other output format (latex / pdf, rtf, docbook, ...) the problem appears in those formats as well and one cannot place e.g. \rtfonly inside \htmlonly

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

Avoid line breaks in last column of table if comments are splitted in pieces

doxygen