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>
This commit is contained in:
Gilles Peskine 2021-02-23 13:40:19 +01:00
parent c86a16548c
commit 5a7702e76d
3 changed files with 30 additions and 21 deletions

View file

@ -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.
*/

View file

@ -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,

View file

@ -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