doxygen style comments in a code block don't render

[ReenigneArcher]

Given the following markdown:

* Multi-line comments, such as for a [documentation block](#documentation-blocks), should use the following format:

  ```cpp
  /**
   * @brief A brief description of the member.
   * More detailed description of the member.
   */
  \`\`\`  <!-- can't get this to render in GitHub, but you get the idea -->

Results in the following:

Currently our docs use sphinx + doxygen, but I am trying to migrate to use doxygen exclusively, via https://github.com/LizardByte/Sunshine/pull/2932

✅ Sphinx version: https://docs.lizardbyte.dev/projects/sunshine/en/master/source_code/source_code.html ❌ Doxygen version: https://lizardbyte--2932.org.readthedocs.build/projects/sunshine/en/2932/md_docs_2source_2source__code_2source__code.html ✅ GitHub markdown version: https://github.com/LizardByte/Sunshine/blob/docs-drop-sphinx-and-use-doxygen-exclusively/docs/source/source_code/source_code.md

[ReenigneArcher]

I found that I can use @verbatim instead of a code block, although then it doesn't do syntax highlighting.

https://github.com/doxygen/doxygen/blob/14fc65f92184f8d788d5fb2723fb28e773dc4a5a/doc/markdown.dox#L734-L747

Is there anyway to get both?

[jothepro]

Code blocks should definitely work as you described! It seems like the link in your post doesn't work anymore. Can you provide an updated link to the Doxygen version with broken code block rendering? What Doxygen version are you using?

[ReenigneArcher]

Here is an example of how it renders using @verbatim: https://docs.lizardbyte.dev/projects/doxyconfig/latest/md_docs_2source__code.html

Here's the markdown source for that: https://github.com/LizardByte/doxyconfig/blob/master/docs/source_code.md

Without verbatim it renders as shown in the screenshot above.

Using commit: https://github.com/jothepro/doxygen-awesome-css/tree/40e9b25b6174dd3b472d8868f63323a870dfeeb8 (latest release)

[jothepro]

I cannot reproduce the issue, when using the Doxygen setup in this repository, the code blocks render just fine. You can also see them working here (code).

I am assuming that there must be something wrong with your setup. Did you apply some custom CSS that may interfere with the code rendering? Is the code present in the DOM and just invisible, or is it not rendered into the HTML by Doxygen at all?

[ReenigneArcher]

Can you try a code block like the following?

@code{cpp}
/**
 * @brief A brief description of the member.
 * More detailed description of the member.
 */
@endcode

It's probably a doxygen issue where it can't render properly because it has nested doxygen style comments. Other code blocks are fine, as long as they don't have the doxygen syntax in them.

[jothepro]

ohh, now I see the problem! I can indeed reproduce the problem when the code contains a Doxygen comment! I agree that this must be a Doxygen issue, as the text of the comment is not contained in the HTML...