From b9e133a9204d0635fa224ac9cc67c3f7d5902b3f Mon Sep 17 00:00:00 2001
From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Mon, 4 Jun 2018 08:28:57 +0200
Subject: [PATCH] doxygen: mention that block-level \m_class has to be
 separated by a newline.

I *really tried* to make it work, but it was not worth the pain.
---
 doc/doxygen.rst | 40 ++++++++++++++++++++++++++++++++++++----
 1 file changed, 36 insertions(+), 4 deletions(-)

diff --git a/doc/doxygen.rst b/doc/doxygen.rst
index ebd29f4b..d2bb35d0 100644
--- a/doc/doxygen.rst
+++ b/doc/doxygen.rst
@@ -777,12 +777,44 @@ formula. Example usage:
 
     .. code:: c++
 
-        /** See the red @m_class{m-danger} @f$ \Sigma @f$ character. */
+        /**
+        A green formula:
+
+        @m_class{m-success}
+
+        @f[
+            e^{i \pi} + 1 = 0
+        @f]
+
+        Use the @m_class{m-label m-warning} **Shift** key.
+        */
+
+    .. role:: label-warning
+        :class: m-label m-warning
+
+    A green formula:
+
+    .. math::
+        :class: m-success
+
+        e^{i \pi} + 1 = 0
 
-    .. role:: math-danger(math)
-        :class: m-danger
+    Use the :label-warning:`Shift` key.
 
-    See the red :math-danger:`\Sigma` character.
+.. note-info::
+
+    Due to parsing ambiguities, in order to affect the whole block with
+    ``@m_class`` instead of just the immediately following inline element, you
+    have to separate it from the paragraph with a blank line:
+
+    .. code:: c++
+
+        /**
+        @m_class{m-text m-green}
+
+        @m_class{m-text m-big}
+        **This text is big,** but the whole paragraph is green.
+        */
 
 The ``@m_footernavigation`` command is similar to ``@tableofcontents``, but
 across pages --- if a page is a subpage of some other page and this command is
-- 
2.30.2