Mark doxygen comments and put them in a separate file / build documentation from source/comment blocks

Question

My question is not easy to describe in a short caption, so i try to explain it more detailed:

I want to generate documentation from comments in the source code. My favorite way would be a separately generated markdown file which contains the collected comment blocks.

Here is an example sourcecode of what I want to do:

/*!
 * @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;
    }
}

The function handles different commands and I want to put the description of the command into the case to have source code and documentation at one place.

As you can see, I tried several possibilities to collect this information with Doxygen. The first solution with html tags works not too bad. The resulting html looks like this:

But its not perfect. As the table is built over several blocks, an extra newline is added after "Dummy" and "Get version" and therefore they are not in line with the "?" and the "v".

My next try was with the \xrefitem. I defined an ALIAS in Doxygen cmditem=\xrefitem cmditems "Commands" "Command overview" and used it for documenting the single items. Doxygen generated additionally to the function an extra "Related pages" entry which looks like this:

The problem is, I don't know how to get this formatted pretty as a table...

And last I tried to write the table in markdown syntax but this works only for the first entry of the table. The second entry which is in a separate comment block was not added to the table.

Does anyone know a way how to get a pretty formatted documentation with separated comment blocks for the different commands?

I need the documentation of the commands to give it to a customer. He does'nt need all the other stuff about the code and the function. So "the cherry on the cake" whould be an instruction/command which tells doxygen to take the comment block "as it is" and put/append it to a separate file.

In this example I'd like to have the markdown comments in one file which could look like this (off course after a little modification of the lines above):

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

Stephan Stephan · Accepted Answer · 2020-11-27T07:01:51

you are right, every comment block is a separate paragraph and therefore Doxygen inserts <p> ... </p> in the table which causes the extra lines.

The generated html code looks like this:

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

Your workaround helps to get a uniform layout of the table entries:

Thank you!

Mark doxygen comments and put them in a separate file / build documentation from source/comment blocks

2 Answers