[rtems-central commit] interface: Use paragraph for notes

Sebastian Huber sebh at rtems.org
Wed Feb 3 05:28:01 UTC 2021


Module:    rtems-central
Branch:    master
Commit:    331cecb5a708f15daf982c7f399600ac2f602bf7
Changeset: http://git.rtems.org/rtems-central/commit/?id=331cecb5a708f15daf982c7f399600ac2f602bf7

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Fri Jan 22 14:15:57 2021 +0100

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(-)

diff --git a/rtemsspec/interface.py b/rtemsspec/interface.py
index 7adf63a..84623dc 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 2ca9623..9f3cf1e 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,



More information about the vc mailing list