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/include/test/psa_exercise_key.h b/tests/include/test/psa_exercise_key.h
index 1613237..57eae58 100644
--- a/tests/include/test/psa_exercise_key.h
+++ b/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 input1_length The length of \p input1 in bytes.
+ * \param input2 The first input to pass.
+ * \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 @@
*
* In case of failure, mark the current test case as failed.
*
- * \param alg A key agreement algorithm compatible with \p key.
- * \param key A key that allows key agreement with \p alg.
+ * \param operation An operation that has been set up for a key
+ * 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 @@
* - Montgomery public key: first byte.
*
* \param type The key type.
- * \param size The key size in bits.
- * \param exported A buffer containing
+ * \param bits The key size in bits.
+ * \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.
*/
diff --git a/tests/suites/host_test.function b/tests/suites/host_test.function
index f4f4f45..d83d751 100644
--- a/tests/suites/host_test.function
+++ b/tests/suites/host_test.function
@@ -360,8 +360,6 @@
/**
* \brief Tests snprintf implementation.
*
- * \param none
- *
* \return 0 for success else 1
*/
static int run_test_snprintf( void )
@@ -428,8 +426,8 @@
* \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 mbedtls_test_info A pointer to the test info structure.
+ * \param ret The test dispatch status (DISPATCH_xxx).
+ * \param info A pointer to the test info structure.
*/
static void write_outcome_result( FILE *outcome_file,
size_t unmet_dep_count,
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
