From 331cecb5a708f15daf982c7f399600ac2f602bf7 Mon Sep 17 00:00:00 2001
From: Sebastian Huber <sebastian.huber@embedded-brains.de>
Date: Fri, 22 Jan 2021 14:15:57 +0100
Subject: interface: Use paragraph for notes

Reorder sections to be in line with the Sphinx documentation.
---
 rtemsspec/interface.py            |  4 ++--
 rtemsspec/tests/test_interface.py | 25 +++++++++++++------------
 2 files changed, 15 insertions(+), 14 deletions(-)

(limited to 'rtemsspec')

diff --git a/rtemsspec/interface.py b/rtemsspec/interface.py
index 7adf63aa..84623dc2 100644
--- a/rtemsspec/interface.py
+++ b/rtemsspec/interface.py
@@ -410,11 +410,10 @@ class Node:
         with content.doxygen_block():
             content.add_ingroup(_get_group_identifiers(ingroups))
             content.add_brief_description(self.substitute_text(item["brief"]))
-            content.doxyfy(self.substitute_text(item["description"]))
-            content.doxyfy(self.substitute_text(item["notes"]))
             if "params" in item:
                 content.add_param_description(item["params"],
                                               self.substitute_text)
+            content.doxyfy(self.substitute_text(item["description"]))
             if "return" in item:
                 ret = item["return"]
                 for retval in ret["return-values"]:
@@ -423,6 +422,7 @@ class Node:
                                      f"@retval {retval['value']} "))
                 content.wrap(self.substitute_text(ret["return"]),
                              initial_indent="@return ")
+            content.add_paragraph("Notes", self.substitute_text(item["notes"]))
         return content
 
     def _add_generic_definition(self, get_lines: GetLines) -> None:
diff --git a/rtemsspec/tests/test_interface.py b/rtemsspec/tests/test_interface.py
index 2ca9623f..9f3cf1e7 100644
--- a/rtemsspec/tests/test_interface.py
+++ b/rtemsspec/tests/test_interface.py
@@ -207,6 +207,14 @@ typedef enum EnumB {
  *
  * @brief Function brief description.
  *
+ * @param Param0 is parameter 0.
+ *
+ * @param[in] Param1 is parameter 1.
+ *
+ * @param[out] Param2 is parameter 2.
+ *
+ * @param[in,out] Param3 is parameter 3.
+ *
  * Function description.  References to VeryLongFunction(), ::Integer, #Enum,
  * #DEFINE, VERY_LONG_MACRO(), #Variable, ::ENUMERATOR_0, Struct, #a,
  * interface, @ref GroupA, and @ref GroupF.  Second parameter is ``Param1``.
@@ -215,14 +223,6 @@ typedef enum EnumB {
  * these two lines
  * are not wrapped
  * @endcode
- *
- * @param Param0 is parameter 0.
- *
- * @param[in] Param1 is parameter 1.
- *
- * @param[out] Param2 is parameter 2.
- *
- * @param[in,out] Param3 is parameter 3.
  */
 void Function( int Param0, const int *Param1, int *Param2, int *Param3 );
 
@@ -367,10 +367,6 @@ typedef uint32_t Integer /* Some comment. */;
  *
  * @brief Very long function brief description.
  *
- * VeryLongFunction description.
- *
- * VeryLongFunction notes.
- *
  * @param VeryLongParam0 is very long parameter 0 with some super important and
  *   extra very long description which makes a lot of sense.
  *
@@ -380,6 +376,8 @@ typedef uint32_t Integer /* Some comment. */;
  *
  * @param[in,out] VeryLongParam3 is very long parameter 3.
  *
+ * VeryLongFunction description.
+ *
  * @retval 1 is returned, in case A.
  *
  * @retval 2 is returned, in case B.
@@ -387,6 +385,9 @@ typedef uint32_t Integer /* Some comment. */;
  * @retval #Enum is returned, in case C.
  *
  * @return Sometimes some value.  See Function().
+ *
+ * @par Notes
+ * VeryLongFunction notes.
  */
 __attribute__((__const__)) static inline int VeryLongFunction(
   int                  VeryLongParam0,
-- 
cgit v1.2.3