From 364d12cfab969b4944793e79e6f9776448c7203d Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 8 Mar 2021 17:23:47 +0100 Subject: [PATCH] Documentation: fix \p used for non-parameters In Doxygen documentation, use \c rather than \p when discussing something that isn't a parameter of the current macro or function. Where needed, explain what the thing is. Signed-off-by: Gilles Peskine --- include/psa/crypto.h | 9 +++++---- include/psa/crypto_se_driver.h | 3 ++- include/psa/crypto_sizes.h | 2 +- 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 78c6e3d1e..7ee3293be 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -3465,7 +3465,8 @@ psa_status_t psa_key_derivation_output_bytes( * state and must be aborted by calling psa_key_derivation_abort(). * * How much output is produced and consumed from the operation, and how - * the key is derived, depends on the key type: + * the key is derived, depends on the key type and on the key size + * (denoted \c bits below): * * - For key types for which the key is an arbitrary sequence of bytes * of a given size, this function is functionally equivalent to @@ -3475,7 +3476,7 @@ psa_status_t psa_key_derivation_output_bytes( * if the implementation provides an isolation boundary then * the key material is not exposed outside the isolation boundary. * As a consequence, for these key types, this function always consumes - * exactly (\p bits / 8) bytes from the operation. + * exactly (\c bits / 8) bytes from the operation. * The following key types defined in this specification follow this scheme: * * - #PSA_KEY_TYPE_AES; @@ -3496,8 +3497,8 @@ psa_status_t psa_key_derivation_output_bytes( * string and process it as specified in RFC 7748 §5. * * - For key types for which the key is represented by a single sequence of - * \p bits bits with constraints as to which bit sequences are acceptable, - * this function draws a byte string of length (\p bits / 8) bytes rounded + * \c bits bits with constraints as to which bit sequences are acceptable, + * this function draws a byte string of length (\c bits / 8) bytes rounded * up to the nearest whole number of bytes. If the resulting byte string * is acceptable, it becomes the key, otherwise the drawn bytes are discarded. * This process is repeated until an acceptable byte string is drawn. diff --git a/include/psa/crypto_se_driver.h b/include/psa/crypto_se_driver.h index f5fe02990..f6e302298 100644 --- a/include/psa/crypto_se_driver.h +++ b/include/psa/crypto_se_driver.h @@ -1061,7 +1061,8 @@ typedef psa_status_t (*psa_drv_se_export_key_t)(psa_drv_se_context_t *drv_contex * \brief A function that generates a symmetric or asymmetric key on a secure * element * - * If \p type is asymmetric (#PSA_KEY_TYPE_IS_ASYMMETRIC(\p type) = 1), + * If the key type \c type recorded in \p attributes + * is asymmetric (#PSA_KEY_TYPE_IS_ASYMMETRIC(\c type) = 1), * the driver may export the public key at the time of generation, * in the format documented for psa_export_public_key() by writing it * to the \p pubkey buffer. diff --git a/include/psa/crypto_sizes.h b/include/psa/crypto_sizes.h index 395683410..0c7ef5c97 100644 --- a/include/psa/crypto_sizes.h +++ b/include/psa/crypto_sizes.h @@ -190,7 +190,7 @@ /** This macro returns the maximum supported length of the PSK for the * TLS-1.2 PSK-to-MS key derivation - * (#PSA_ALG_TLS12_PSK_TO_MS(\p hash_alg)). + * (#PSA_ALG_TLS12_PSK_TO_MS(\c hash_alg)). * * The maximum supported length does not depend on the chosen hash algorithm. *