Math that works in MrDocs through Antora is incompatible with clang or Doxygen

[correaa]

After some effort (and help from Alan), I managed to add math to mrdocs-based documentation (+antora).
https://gitlab.com/correaa/boost-multi/-/tree/develop/doc/mrdocs-addons?ref_type=heads

However, now I notice that the code to achieve this is incompatible with some clang warnings.

https://cpplang.slack.com/archives/C0508A7LWUV/p1784619895907419

clang 22 -Wdocumentation-unknown-command warning on LaTeX-style math in doc comments (Windows)

Description

Building with clang 22 on Windows, documentation comments using inline LaTeX math (e.g. $A^\mathrm{T}$) trigger a -Wdocumentation-unknown-command warning/error. Clang's documentation parser interprets \mathrm as an unrecognized Doxygen-style command tag, rather than as part of a math expression.

Example

In file included from C:\Users\correaa\boost-multi\include\boost/multi/array.hpp:9:
C:\Users\correaa\boost-multi\include\boost/multi/array_ref.hpp(1722,26): error: unknown command tag name [-Werror,-Wdocumentation-unknown-command]
 1722 |         /// A transpose view $A^\mathrm{T}$, that exchanges the first two indices
      |

Discussion

• Clang's doc-comment parser doesn't treat $...$ as a math delimiter on its own; Doxygen's convention is \f$ ... \f$ for inline math, which clang (or clang-doc) presumably recognizes/ignores appropriately.
• Without \f$, clang sees the bare \mathrm inside $...$ as an attempted command tag and flags it as unknown — which is arguably "correct" behavior from clang's point of view, even though it's not actually using Doxygen conventions to render anything.
• Not obviously fixable in general: mrdocs/clang-doc has its own set of recognized commands, some of which plain clang doesn't know either, so there's no single convention that satisfies both.
• Possible mitigations to consider: switch to \f$ ... \f$ for inline math consistently, suppress -Wdocumentation-unknown-command for this warning specifically, or avoid backslash commands like \mathrm inside math delimiters in doc comments.

Environment

• clang 22, Windows

[correaa]

At the risk of being repetitive (I haven't been following what direction the solution is taking), this is how I work around this in actual code:

...
#if defined(__clang__)
#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wdocumentation-unknown-command"  // TODO(correaa) for latex documentation in MrDocs
#endif
	/// A transpose view $A^\mathrm{T}$, that exchanges the first two indices
	BOOST_MULTI_HD constexpr auto transposed() const& -> const_subarray { return transposed_aux_(); }  // cppcheck-suppress duplInheritedMember ; to overwrite
#if defined(__clang__)
#pragma clang diagnostic pop
#endif

[correaa]

update: I was able to reproduce this with clang Linux after some updates