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>

tests/include/test/psa_exercise_key.h

@@ -133,8 +133,8 @@
  * \param alg               The algorithm to use.
  * \param input1            The first input to pass.
  * \param input1_length     The length of \p input1 in bytes.
- * \param input1            The first input to pass.
+ * \param input2            The first input to pass.
- * \param input1_length     The length of \p input1 in bytes.
+ * \param input2_length     The length of \p input2 in bytes.
  * \param capacity          The capacity to set.
  *
  * \return                  \c 1 on success, \c 0 on failure.
@@ -170,8 +170,11 @@ psa_status_t mbedtls_test_psa_raw_key_agreement_with_self(
  *
  * In case of failure, mark the current test case as failed.
  *
- * \param alg               A key agreement algorithm compatible with \p key.
+ * \param operation         An operation that has been set up for a key
- * \param key               A key that allows key agreement with \p alg.
+ *                          agreement algorithm that is compatible with
+ *                          \p key.
+ * \param key               A key pair object that is suitable for a key
+ *                          agreement with \p operation.
  *
  * \return                  \c 1 on success, \c 0 on failure.
  */
@@ -191,8 +194,9 @@ psa_status_t mbedtls_test_psa_key_agreement_with_self(
  * - Montgomery public key: first byte.
  *
  * \param type              The key type.
- * \param size              The key size in bits.
+ * \param bits              The key size in bits.
- * \param exported          A buffer containing
+ * \param exported          A buffer containing the key representation.
+ * \param exported_length   The length of \p exported in bytes.
  *
  * \return                  \c 1 if all checks passed, \c 0 on failure.
  */

tests/suites/host_test.function

@@ -360,8 +360,6 @@ static int test_snprintf( size_t n, const char *ref_buf, int ref_ret )
 /**
  * \brief       Tests snprintf implementation.
  *
- * \param none
- *
  * \return      0 for success else 1
  */
 static int run_test_snprintf( void )
@@ -428,8 +426,8 @@ static void write_outcome_entry( FILE *outcome_file,
  * \param unmet_dependencies         The array of unmet dependencies.
  * \param missing_unmet_dependencies Non-zero if there was a problem tracking
  *                                   all unmet dependencies, 0 otherwise.
- * \param ret                   The test dispatch status (DISPATCH_xxx).
+ * \param ret                        The test dispatch status (DISPATCH_xxx).
- * \param mbedtls_test_info     A pointer to the test info structure.
+ * \param info                       A pointer to the test info structure.
  */
 static void write_outcome_result( FILE *outcome_file,
                                   size_t unmet_dep_count,

tests/suites/main_test.function

@@ -105,7 +105,7 @@ $expression_code
  *              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 @@ $dep_check_code
 /**
  * \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
+ * \param param_array   The array of parameters. Each element is a `void *`
- *                  function parameters.
+ *                      which the wrapper casts to the correct type and
- *
+ *                      dereferences. Each wrapper function hard-codes the
- * \return       void
+ *                      number and types of the parameters.
  */
-typedef void (*TestWrapper_t)( void ** );
+typedef void (*TestWrapper_t)( void **param_array );
 
 
 /**
@@ -158,8 +162,8 @@ $dispatch_code
  *               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 fp     Function pointer to the test function.
- * \param params Parameters to pass
+ * \param params Parameters to pass to the #TestWrapper_t wrapper function.
  *
  */
 void execute_function_ptr(TestWrapper_t fp, void **params)
@@ -197,7 +201,9 @@ void execute_function_ptr(TestWrapper_t fp, void **params)
 /**
  * \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 @@ int dispatch_test( size_t func_idx, void ** params )
 
 
 /**
- * \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