`/*` in line in \code block causes `*` on subsequent lines

[paul-j-lucas]

Doxygen 1.8.18, when run on this file bug.doxy.gz with this configuration file Doxyfile.gz, produces this incorrect HTML file _bug.html.gz that looks like this:

That is, the * on the first line inside the \code block incorrectly causes * to be placed at the beginning of all subsequent lines within that block.

[paul-j-lucas]

I think it's because it parses /* as the start of a comment (which it shouldn't be doing inside a \code block).

[albert-github]

The problem is indeed due to the `/*. This is due to the fact that there is, after an internal doxygen comment conversion, a nested comment and this is not allowed.

Possible solutions (the first 2 are the best ones in my opinion):

• why use cpp as "language" and not just markdown (i.e. md), has the advantage that you can also remove the comment signs.
• don't use \code / \endcode but ```
• don't use \code but put (at least) 4 spaces befor rm and mkdir:

  ///     rm -rf /root/chroot/*
  ///     mkdir -p /root/chroot

• convert the comment the /** comment without preceding * on the following lines and use \verbatim instead of \code

[paul-j-lucas]

This is due to the fact that there is, after an internal doxygen comment conversion, a nested comment and this is not allowed.

@code should pass through everything as-is until @endcode. It shouldn't be trying to parse internal comments at all.

why use cpp as "language" and not just markdown

Because the larger body of documentation makes reference to C++ symbols in the codebase that is also documented with Doxygen. If the Doxygen file were Markdown, it wouldn't auto-link to those symbols.

don't use \code / \endcode but ```

That works (so thanks for the workaround), but those should be treated exactly the same. `` is just the Markdown syntax for@code`.

use \verbatim instead of\code

But \verbatim doesn't put the box around the text (which I like).

[paul-j-lucas]

By the way, you haven't explained why Doxygen decides to insert a leading * on the lines. In what use case would that ever be the correct thing to do?

[albert-github]

There are always problems with nested comments and some parts of doxygen have some workarounds for it (although it is against the standard).

The argument

Because the larger body of documentation makes reference to C++ symbols in the codebase that is also documented with Doxygen. If the Doxygen file were Markdown, it wouldn't auto-link to those symbols.

is in my opinion not valid, doxygen will still link to the right entities and for code coloring one can always use ```.cpp

The insertion of the * is done so things like /// *, i.e. lists are still working after comment conversion.

[paul-j-lucas]

is in my opinion not valid, doxygen will still link to the right entities and for code coloring one can always use ```.cpp

It's been a while since I decided on using ///, so I don't remember the reason. But I do remember comparing using /// vs .md and there was some reason .md just didn't work right. Maybe I can try to re-figure out what that reason is.

That aside, is there a justification for having `` and@codework differently? Again, they should behave exactly the same (which means in this case that@code` should work like ``` since the behavior of ``` for my example works correctly).

The insertion of the * is done so things like /// *, i.e. lists are still working after comment conversion.

The * should trigger a a list only if the * is the first non-whitespace character on a line (after the leading /// or other comment characters are stripped). There is no way that:

foo/*

should trigger the start of a list.

[albert-github]

Regarding the * :

so things like /// *, i.e. lists are still working after comment conversion.

just intended that what you wrote like:

The * should trigger a a list only if the * is the first non-whitespace character on a line (after the leading /// or other comment characters are stripped).

The difference between ``` and \code lies in the way they are handled before the conversion of ``` to \code.

[paul-j-lucas]

The difference between `` and\codelies in the way they are handled before the conversion of \``` to\code`.

My point is that the end result should be such that there is no difference between `` and\code` at all. You haven't explained why there needs to be a user-perceivable difference.

[paul-j-lucas]

I remembered at least part of the reason why I used /// and not .md. In .md, I'm limited only to what Markdown supports. Doxygen has things like @note, @warning, @tableofcontents and other commands that have no equivalents in Markdown.

[albert-github]

That cannot be the reason as these things are independent from the usage of /// and /**.

[paul-j-lucas]

A valid (and strictly Markdown) .md file does not support @note, @warning, etc. That means I can't use an .md file if I want to use those Doxygen commands. The only other option is to use a "source" file which is why I tell Doxygen to use a .doxy file and treat it as if it were a C++ source file.

In a valid C++ source file, Doxygen comments must be "special" versions of the host language's comments. For C++, that means either within /** ... */ or ///. I chose ///.

[arwedus]

@albert-github, is it actually intented behavior that doxygen commands inside a Markdown verbatim section (4 spaces indentation) or code block (triple backticks) is still parsed by doxygen?

It took me really a while to figure that out and I first thought that it is a bug. Code and verbatim sections in Commonmark spec have the property that anything inside them is not further parsed. Kind of like doxygen's own \verbatim section.

[albert-github]

@arwedus Can you give a small example of the problem you see?

As far as I can see from your question, yes this is intended behavior, at least when you specify in the language used (in a markdown file explicitly, in a "language" file it is implicitly done). The language is used for e.g. code coloring.

It looks like that the explicitly specifying in some e.g. .h file:

/** \file

```{.c}
  //  bacticks c ext
  void fie_b4(void);
```
*/

the {.c} isn't properly seen, contrary to:

/** \file
 *
 * ```{.c}
 *   // bacticks c ext
 *   void fie_b4(void);
 * ```
*/

Note that the ~~~ is seen properly in both cases.

For the later problem: I've just pushed a proposed patch, pull request #8908

[albert-github]

The pull request #8908 has been integrated in master on GitHub (please don't close the issue as this will be done at the moment of an official release).

[arwedus]

@albert-github I guess this is it's own issue, but the manual does not mention anywhere that doxygen commands inside of preformatted or code sections are parsed. Example:

/** Testing Doxygen special commands inside code sections
 * 
 * Code section:
 * 
 * \code
 * - \todo creates a todo item (if not in code section)
 * - \verbatim creates a verbatim section but not here
 * \endcode
 * 
 * Markdown code section:
 * 
 * ```
 *  _________________________________________________
 *  |                                                |
 *  |  \todo outside code block creates a todo item  |
 *  |________________________________________________|
 *  \verbatim creates a verbatim section but not here
 * ```
 * 
 * Markdown preformatted section:
 * 
 *       ________________________________________________________________
 *      |                                                                |
 *      |  \todo here creates no todo-item                               |
 *      |  \verbatim creates a verbatim section even here \endverbatim   |
 *      |________________________________________________________________|
 *    
 * 
 * \<pre\>formatted section:
 * 
 * <pre>  \\todo inside pre-block would fail  </pre>
 */

• Doxygen does not parse any special commands in the first two, but in the latter two. Even there in the preformatted Markdown behavior seems to be inconsistent. The \todo command is not parsed, but the \endverbatim is for some reason parsed.

Maybe this is just another reason for you to mark the \verbatim command as internal 😆

[albert-github]

Looks like a nice corner case, as doxygen translates a markdown pre-formatted section ("4 spaces" section) / code block into a \verbatim section a small problem occurs when there is a \endverbatim in it.

I think it is worthwhile to have a new issue about this, though as this is a real corner-case I'm not sure whether it is worth fixing. Although it is very inconvenient and each problem is a problem to much and this might be reasonable easy to fix (defining a new internal command). (Problem might be present with other substitutions as well. i.e. with ``` which translates into \code ....)

I don't understand what you mean with <pre> \\todo inside pre-block would fail </pre>

[albert-github]

Unfortunately no, separate, issue created for the problem as mentioned in: https://github.com/doxygen/doxygen/issues/7807#issuecomment-977975829, I've just pushed a proposed patch, pull request #8912

[albert-github]

Regarding the problem mentioned in https://github.com/doxygen/doxygen/issues/7807#issuecomment-977975829, Code has been integrated in master on GitHub (please don't close the issue as more issues were mentioned in this issue).