Fix some C function documentation in the test framework

The primary goal of this commit is to fix various comments where
`clang -Wdocumentation` identified a discrepancy between the actual
function parameters and the documented parameters. The discrepancies
were due to copypasta, formatting issues or documentation that had
diverged from the implementation.

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/tests/suites/main_test.function b/tests/suites/main_test.function
index aa408ea..36a7d23 100644
--- a/tests/suites/main_test.function
+++ b/tests/suites/main_test.function
@@ -105,7 +105,7 @@
  *              Identifiers and check code is generated by script:
  *              $generator_script
  *
- * \param exp_id    Dependency identifier.
+ * \param dep_id    Dependency identifier.
  *
  * \return       DEPENDENCY_SUPPORTED if set else DEPENDENCY_NOT_SUPPORTED
  */
@@ -129,13 +129,17 @@
 /**
  * \brief       Function pointer type for test function wrappers.
  *
+ * A test function wrapper decodes the parameters and passes them to the
+ * underlying test function. Both the wrapper and the underlying function
+ * return void. Test wrappers assume that they are passed a suitable
+ * parameter array and do not perform any error detection.
  *
- * \param void **   Pointer to void pointers. Represents an array of test
- *                  function parameters.
- *
- * \return       void
+ * \param param_array   The array of parameters. Each element is a `void *`
+ *                      which the wrapper casts to the correct type and
+ *                      dereferences. Each wrapper function hard-codes the
+ *                      number and types of the parameters.
  */
-typedef void (*TestWrapper_t)( void ** );
+typedef void (*TestWrapper_t)( void **param_array );
 
 
 /**
@@ -158,8 +162,8 @@
  *               parameter failure callback, to be used. Calls to setjmp()
  *               can invalidate the state of any local auto variables.
  *
- * \param fp     Function pointer to the test function
- * \param params Parameters to pass
+ * \param fp     Function pointer to the test function.
+ * \param params Parameters to pass to the #TestWrapper_t wrapper function.
  *
  */
 void execute_function_ptr(TestWrapper_t fp, void **params)
@@ -197,7 +201,9 @@
 /**
  * \brief        Dispatches test functions based on function index.
  *
- * \param exp_id    Test function index.
+ * \param func_idx    Test function index.
+ * \param params      The array of parameters to pass to the test function.
+ *                    It will be decoded by the #TestWrapper_t wrapper function.
  *
  * \return       DISPATCH_TEST_SUCCESS if found
  *               DISPATCH_TEST_FN_NOT_FOUND if not found
@@ -226,9 +232,10 @@
 
 
 /**
- * \brief       Checks if test function is supported
+ * \brief       Checks if test function is supported in this build-time
+ *              configuration.
  *
- * \param exp_id    Test function index.
+ * \param func_idx    Test function index.
  *
  * \return       DISPATCH_TEST_SUCCESS if found
  *               DISPATCH_TEST_FN_NOT_FOUND if not found