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:
parent
c86a16548c
commit
5a7702e76d
3 changed files with 30 additions and 21 deletions
|
@ -133,8 +133,8 @@
|
||||||
* \param alg The algorithm to use.
|
* \param alg The algorithm to use.
|
||||||
* \param input1 The first input to pass.
|
* \param input1 The first input to pass.
|
||||||
* \param input1_length The length of \p input1 in bytes.
|
* \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.
|
* \param capacity The capacity to set.
|
||||||
*
|
*
|
||||||
* \return \c 1 on success, \c 0 on failure.
|
* \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.
|
* 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.
|
* \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.
|
* - Montgomery public key: first byte.
|
||||||
*
|
*
|
||||||
* \param type The key type.
|
* \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.
|
* \return \c 1 if all checks passed, \c 0 on failure.
|
||||||
*/
|
*/
|
||||||
|
|
|
@ -360,8 +360,6 @@ static int test_snprintf( size_t n, const char *ref_buf, int ref_ret )
|
||||||
/**
|
/**
|
||||||
* \brief Tests snprintf implementation.
|
* \brief Tests snprintf implementation.
|
||||||
*
|
*
|
||||||
* \param none
|
|
||||||
*
|
|
||||||
* \return 0 for success else 1
|
* \return 0 for success else 1
|
||||||
*/
|
*/
|
||||||
static int run_test_snprintf( void )
|
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 unmet_dependencies The array of unmet dependencies.
|
||||||
* \param missing_unmet_dependencies Non-zero if there was a problem tracking
|
* \param missing_unmet_dependencies Non-zero if there was a problem tracking
|
||||||
* all unmet dependencies, 0 otherwise.
|
* 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,
|
static void write_outcome_result( FILE *outcome_file,
|
||||||
size_t unmet_dep_count,
|
size_t unmet_dep_count,
|
||||||
|
|
|
@ -105,7 +105,7 @@ $expression_code
|
||||||
* Identifiers and check code is generated by script:
|
* Identifiers and check code is generated by script:
|
||||||
* $generator_script
|
* $generator_script
|
||||||
*
|
*
|
||||||
* \param exp_id Dependency identifier.
|
* \param dep_id Dependency identifier.
|
||||||
*
|
*
|
||||||
* \return DEPENDENCY_SUPPORTED if set else DEPENDENCY_NOT_SUPPORTED
|
* \return DEPENDENCY_SUPPORTED if set else DEPENDENCY_NOT_SUPPORTED
|
||||||
*/
|
*/
|
||||||
|
@ -129,13 +129,17 @@ $dep_check_code
|
||||||
/**
|
/**
|
||||||
* \brief Function pointer type for test function wrappers.
|
* \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()
|
* parameter failure callback, to be used. Calls to setjmp()
|
||||||
* can invalidate the state of any local auto variables.
|
* 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)
|
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.
|
* \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
|
* \return DISPATCH_TEST_SUCCESS if found
|
||||||
* DISPATCH_TEST_FN_NOT_FOUND if not 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
|
* \return DISPATCH_TEST_SUCCESS if found
|
||||||
* DISPATCH_TEST_FN_NOT_FOUND if not found
|
* DISPATCH_TEST_FN_NOT_FOUND if not found
|
||||||
|
|
Loading…
Reference in a new issue