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

Question

I am documenting my C/C++ code with doxygen. I want to collect the documentation for a (long) list of parameters in one single table: Each row of the table should have a short piece of code such that each parameter is documented where it is handled (e.g., first column parameter name, second column parameter explanation / default value / etc.). So, it is required the the comments of this long table are fragmented into many pieces.

Consider the following piece of documentation. A first table has an “interruption” while the second has 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> 
} 

In the same directory as this file (called main.cpp), I run doxygen -g cfg and doxygen cfg. This creates (among others) a file html/main_8cpp.html. The doxygen version is 1.8.17.

The output of the first table is not really satisfying. Splitting the comment for the table leads to an unintended line break, and subsequently an ugly appearance of the entry in the last column.

I tried manually ending the row of the table with </td> </tr> but the line-breaking behavior stayed the same. Can this behaviour be avoided?

If I look into the html source, the output of the two tables is different.

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

The problem is the paragraph <p class="starttd">2 <br /> </p> (the <p>tags, not the <br>). If I remove them, the line break dissapears.

Answer 1

A bit to long for a comment.

The first thought is that the problem is caused by the fact that some lines have trailing spaces and when there are a least 2 trailing spaces this is in markdown see as an indication for an extra line break. Looking at your input (with vi and setting it in list mode, hence the dollar sign at the end) we see:

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

when looking with doxygen -d markdown (I used for your convenience 1.8.17 as well) we see (excerpt):

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

=========

and hence the extra line break.

When removing at the extra spaces in the lines we still see the same problem (only the <br> line is gone in the markdown output). Also disabling the usage of Markdown doesn't help.

This brings us to the further thought that when doxygen sees 2 detailed sections it will try to treat both sections as separate paragraphs (this is normally quite logical) though in this case it has the effect you see. I see the same effect in the 1.8.18 version as well as in in the current master (1.8.19 (3040df2f0aa29a4207de5b37da1d20e3d27340bb)).

I don't think a lot can be done without breaking other code, but this has to be investigated.

As a side note: It is a bit strange to me that the not closed <table> in a comment block doesn't trigger a warning and even more strange to me is that the starting </table> doesn't trigger a warning.

edit

OP brought up a nice idea:

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 <!-- and start the next one with --> \endhtmlonly, the ‘break’ in the details section is commented out.

One has to place a small note with it:

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