From 5a7702e76da7454861d5b9ecbd19da492141ecf2 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 23 Feb 2021 13:40:19 +0100 Subject: [PATCH] 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 --- tests/include/test/psa_exercise_key.h | 16 +++++++++------ tests/suites/host_test.function | 6 ++---- tests/suites/main_test.function | 29 +++++++++++++++++---------- 3 files changed, 30 insertions(+), 21 deletions(-) diff --git a/tests/include/test/psa_exercise_key.h b/tests/include/test/psa_exercise_key.h index 161323738..57eae5891 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 @@ 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 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 @@ 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 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 f4f4f45bd..d83d751ec 100644 --- a/tests/suites/host_test.function +++ b/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 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 aa408eaaf..36a7d231e 100644 --- a/tests/suites/main_test.function +++ b/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 - * 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 @@ $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 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 @@ 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