validation: Add test documentation to group

3 files changed, 60 insertions, 71 deletions

diff --git a/rtemsspec/tests/spec-validation/ts.yml b/rtemsspec/tests/spec-validation/ts.yml
index ee89c4fc..83fbc05a 100644
--- a/rtemsspec/tests/spec-validation/ts.yml
+++ b/rtemsspec/tests/spec-validation/ts.yml
@@ -6,6 +6,7 @@ copyrights:
 description: The Blue Green description.
 enabled-by: true
 links: []
+test-brief: The Blue Green brief description.
 test-code: |
   /* Blue green code */
 test-description: The Blue Green description.
diff --git a/rtemsspec/tests/test_validation.py b/rtemsspec/tests/test_validation.py
index bb7d1da2..c3cf2233 100644
--- a/rtemsspec/tests/test_validation.py
+++ b/rtemsspec/tests/test_validation.py
@@ -92,7 +92,7 @@ def test_validation(tmpdir):
  *
  * @ingroup RTEMSTestSuites
  *
- * @brief Test Suite
+ * @brief The Blue Green brief description.
  *
  * The Blue Green description.
  *
@@ -158,7 +158,9 @@ def test_validation(tmpdir):
  *
  * @ingroup RTEMSTestSuiteTs
  *
- * @brief Test Case
+ * @brief Test rtems_task_ident() brief description.
+ *
+ * Test rtems_task_ident() description.
  *
  * @{
  */
@@ -730,10 +732,6 @@ static void Directive_Action( Directive_Context *ctx )
 
 /**
  * @fn void T_case_body_Directive( void )
- *
- * @brief Test rtems_task_ident() brief description.
- *
- * Test rtems_task_ident() description.
  */
 T_TEST_CASE_FIXTURE( Directive, &Directive_Fixture )
 {
@@ -807,16 +805,6 @@ T_TEST_CASE_FIXTURE( Directive, &Directive_Fixture )
  *
  * @ingroup RTEMSTestSuiteTs
  *
- * @brief Test Case
- *
- * @{
- */
-
-/* Test case support code */
-
-/**
- * @fn void T_case_body_Tc( void )
- *
  * @brief Test case brief description.
  *
  * Test case description.
@@ -834,6 +822,14 @@ T_TEST_CASE_FIXTURE( Directive, &Directive_Fixture )
  *   - Test case action 1 check 0 description.
  *
  *   - Test case action 1 check 1 description.
+ *
+ * @{
+ */
+
+/* Test case support code */
+
+/**
+ * @fn void T_case_body_Tc( void )
  */
 T_TEST_CASE( Tc )
 {
@@ -859,14 +855,6 @@ T_TEST_CASE( Tc )
  *
  * @ingroup RTEMSTestSuiteTs
  *
- * @brief Test Case
- *
- * @{
- */
-
-/**
- * @fn void T_case_body_Tc2( void )
- *
  * @brief Test case 2 brief description.
  *
  * Test case 2 description.
@@ -880,6 +868,12 @@ T_TEST_CASE( Tc )
  *   - Test case 2 action 0 check 1 description.
  *
  * - Test case 2 action 1 description.
+ *
+ * @{
+ */
+
+/**
+ * @fn void T_case_body_Tc2( void )
  */
 T_TEST_CASE_FIXTURE( Tc2, &test_case_2_fixture )
 {
@@ -945,14 +939,6 @@ T_TEST_CASE_FIXTURE( Tc2, &test_case_2_fixture )
  *
  * @ingroup RTEMSTestSuiteTs
  *
- * @brief Test Case
- *
- * @{
- */
-
-/**
- * @fn void T_case_body_Tc3( void )
- *
  * @brief Test case 3 brief description.
  *
  * Test case 3 description.
@@ -962,6 +948,12 @@ T_TEST_CASE_FIXTURE( Tc2, &test_case_2_fixture )
  * - Test case 3 action 0 description.
  *
  *   - Test case 3 action 0 check 0 description.
+ *
+ * @{
+ */
+
+/**
+ * @fn void T_case_body_Tc3( void )
  */
 T_TEST_CASE( Tc3 )
 {
@@ -978,17 +970,15 @@ T_TEST_CASE( Tc3 )
  *
  * @ingroup RTEMSTestSuiteTs
  *
- * @brief Test Case
+ * @brief Test case 4 brief description.
+ *
+ * Test case 4 description.
  *
  * @{
  */
 
 /**
  * @fn void T_case_body_Tc4( void )
- *
- * @brief Test case 4 brief description.
- *
- * Test case 4 description.
  */
 T_TEST_CASE( Tc4 )
 {
@@ -1002,7 +992,23 @@ T_TEST_CASE( Tc4 )
  *
  * @ingroup RTEMSTestSuiteTs
  *
- * @brief Test Case
+ * @brief Test case 5 brief description.
+ *
+ * Test case 5 description.
+ *
+ * This test case performs the following actions:
+ *
+ * - Test case action 0 description.
+ *
+ *   - Test case action 0 check 0 description.
+ *
+ *   - Test case action 0 check 1 description.
+ *
+ * - Test case action 1 description.
+ *
+ *   - Test case action 1 check 0 description.
+ *
+ *   - Test case action 1 check 1 description.
  *
  * @{
  */
@@ -1038,8 +1044,6 @@ void Tc5_Run( int *a, int b, int *c )
  *
  * @ingroup RTEMSTestSuiteTs
  *
- * @brief Test Case
- *
  * @{
  */
 
@@ -1104,23 +1108,7 @@ extern "C" {
 /* Header code for Tc5_Run() */
 
 /**
- * @brief Test case 5 brief description.
- *
- * Test case 5 description.
- *
- * This test case performs the following actions:
- *
- * - Test case action 0 description.
- *
- *   - Test case action 0 check 0 description.
- *
- *   - Test case action 0 check 1 description.
- *
- * - Test case action 1 description.
- *
- *   - Test case action 1 check 0 description.
- *
- *   - Test case action 1 check 1 description.
+ * @brief Runs the parameterized test case.
  *
  * @param[in] a Parameter A description.
  *
@@ -1187,6 +1175,7 @@ extern "C" {
  */
 
 /**
+ * @brief Runs the parameterized test case.
  */
 void Tc6_Run( void );
 
@@ -1278,9 +1267,7 @@ typedef enum {
 /* Header code for Action 2 with Action2_Run() */
 
 /**
- * @brief Test brief.
- *
- * Test description.
+ * @brief Runs the parameterized test case.
  *
  * @param[in] a Parameter A description.
  *
@@ -1348,7 +1335,9 @@ void Action2_Run( int *a, int b, int *c );
  *
  * @ingroup RTEMSTestSuiteTs
  *
- * @brief Test Case
+ * @brief Test brief.
+ *
+ * Test description.
  *
  * @{
  */
diff --git a/rtemsspec/validation.py b/rtemsspec/validation.py
index 17f4e8e4..57cfb4c8 100644
--- a/rtemsspec/validation.py
+++ b/rtemsspec/validation.py
@@ -152,7 +152,10 @@ class _TestItem:
         """ Adds the test case description. """
         with content.defgroup_block(self.group_identifier, self.name):
             _add_ingroup(content, test_case_to_suites[self.uid])
-            content.add(["@brief Test Case", "", "@{"])
+            content.add_brief_description(self.brief)
+            content.wrap(self.description)
+            self.add_test_case_action_description(content)
+            content.add("@{")
 
     def add_test_case_action_description(self, content: CContent) -> None:
         """ Adds the test case action description. """
@@ -189,9 +192,7 @@ class _TestItem:
         """ Adds the test header body. """
         content.add(self.substitute_code(header["code"]))
         with content.doxygen_block():
-            content.add_brief_description(self.substitute_text(self.brief))
-            content.wrap(self.substitute_text(self.description))
-            self.add_test_case_action_description(content)
+            content.add_brief_description("Runs the parameterized test case.")
             content.add_param_description(header["run-params"])
         content.gap = False
         content.declare_function("void", f"{self.ident}_Run",
@@ -248,9 +249,7 @@ class _TestItem:
             align = False
             with content.function_block(
                     f"void T_case_body_{self.ident}( void )"):
-                content.add_brief_description(self.brief)
-                content.wrap(self.description)
-                self.add_test_case_action_description(content)
+                pass
             content.gap = False
         with content.function(ret, name, params, align=align):
             content.add(self.substitute_code(self["test-prologue"]))
@@ -281,7 +280,8 @@ class _TestSuiteItem(_TestItem):
     def generate(self, content: CContent, _base_directory: str,
                  _test_case_to_suites: Dict[str, List[_TestItem]]) -> None:
         with content.defgroup_block(self.group_identifier, self.name):
-            content.add(["@ingroup RTEMSTestSuites", "", "@brief Test Suite"])
+            content.add("@ingroup RTEMSTestSuites")
+            content.add_brief_description(self.brief)
             content.wrap(self.description)
             content.add("@{")
         content.add(self.substitute_code(self["test-code"]))
@@ -615,8 +615,7 @@ class _TestDirectiveItem(_TestItem):
         else:
             with content.function_block(
                     f"void T_case_body_{self.ident}( void )"):
-                content.add_brief_description(self.brief)
-                content.wrap(self.description)
+                pass
             content.gap = False
             ret = ""
             name = "T_TEST_CASE_FIXTURE"