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.

diff --git a/doc/doxygen.rst b/doc/doxygen.rst
index ebd29f4b2ad36fdfa8ec8f412b97afc2870acaca..d2bb35d0c9c830fd40a24bab9c2f6c10fc2ad8c9 100644 (file)
--- 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