[rtems-central commit] interface*: Document only params with description

[Sebastian Huber]

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

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Tue Feb  2 14:05:55 2021 +0100

interface*: Document only params with description

---

 rtemsspec/content.py                    |  6 ++++--
 rtemsspec/interfacedoc.py               | 10 ++++++----
 rtemsspec/tests/spec-interface/func.yml |  4 ++++
 rtemsspec/tests/test_interface.py       |  8 +++++++-
 rtemsspec/tests/test_interfacedoc.py    |  8 +++++++-
 5 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/rtemsspec/content.py b/rtemsspec/content.py
index 9e4049c..7f65949 100644
--- a/rtemsspec/content.py
+++ b/rtemsspec/content.py
@@ -950,8 +950,10 @@ class CContent(Content):
             substitute: Callable[[Optional[str]], str] = _make_str) -> None:
         """ Adds a list of parameter descriptions. """
         for param in params:
-            self.wrap(param["name"] + " " + substitute(param["description"]),
-                      initial_indent=_PARAM[param["dir"]])
+            description = param["description"]
+            if description:
+                self.wrap(param["name"] + " " + substitute(description),
+                          initial_indent=_PARAM[param["dir"]])
 
     def add_description_block(self, brief: Optional[str],
                               description: Optional[str]) -> None:
diff --git a/rtemsspec/interfacedoc.py b/rtemsspec/interfacedoc.py
index 05f24b7..e45fd93 100644
--- a/rtemsspec/interfacedoc.py
+++ b/rtemsspec/interfacedoc.py
@@ -175,10 +175,12 @@ def _generate_directive(content: SphinxContent, mapper: _Mapper,
     if item["params"]:
         content.add(".. rubric:: PARAMETERS:")
         for param in item["params"]:
-            content.add_definition_item(
-                f"``{_sanitize_name(param['name'])}``",
-                mapper.substitute(f"This parameter {param['description']}"),
-                wrap=True)
+            description = param["description"]
+            if description:
+                content.add_definition_item(
+                    f"``{_sanitize_name(param['name'])}``",
+                    mapper.substitute(f"This parameter {description}"),
+                    wrap=True)
     if item["description"]:
         content.add(".. rubric:: DESCRIPTION:")
         content.wrap(mapper.substitute(item["description"]))
diff --git a/rtemsspec/tests/spec-interface/func.yml b/rtemsspec/tests/spec-interface/func.yml
index 75d9a5c..f12bbe2 100644
--- a/rtemsspec/tests/spec-interface/func.yml
+++ b/rtemsspec/tests/spec-interface/func.yml
@@ -11,6 +11,7 @@ definition:
     - const int *${.:/params[1]/name}
     - int *${.:/params[2]/name}
     - int *${.:/params[3]/name}
+    - int *${.:/params[4]/name}
     return: void
   variants: []
 description: |
@@ -48,6 +49,9 @@ params:
 - description: is parameter 3.
   dir: inout
   name: Param3
+- description: null
+  dir: null
+  name: Param4
 return:
   return: null
   return-values: []
diff --git a/rtemsspec/tests/test_interface.py b/rtemsspec/tests/test_interface.py
index 76331ad..b3bf4d3 100644
--- a/rtemsspec/tests/test_interface.py
+++ b/rtemsspec/tests/test_interface.py
@@ -231,7 +231,13 @@ typedef enum EnumB {
  * * Constraint A for Function().
  * @endparblock
  */
-void Function( int Param0, const int *Param1, int *Param2, int *Param3 );
+void Function(
+  int        Param0,
+  const int *Param1,
+  int       *Param2,
+  int       *Param3,
+  int       *Param4
+);
 
 /* Generated from spec:/macro */
 
diff --git a/rtemsspec/tests/test_interfacedoc.py b/rtemsspec/tests/test_interfacedoc.py
index 54f9e1e..d079ef1 100644
--- a/rtemsspec/tests/test_interfacedoc.py
+++ b/rtemsspec/tests/test_interfacedoc.py
@@ -433,7 +433,13 @@ Function brief description.
 
 .. code-block:: c
 
-    void Function( int Param0, const int *Param1, int *Param2, int *Param3 );
+    void Function(
+      int        Param0,
+      const int *Param1,
+      int       *Param2,
+      int       *Param3,
+      int       *Param4
+    );
 
 .. rubric:: PARAMETERS: