Make \retval commands non-empty
Pacify Clang >=15 which complained:
```
include/psa/crypto.h:91:23: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
* \retval #PSA_SUCCESS
~~~~~~~~~~~~~~~~~~~^
```
This commit performs the following systematic replacement:
```
perl -i -0777 -p -e 's/([\\@])(retval +\S+)\n(?! *\*? *([^\n \\*\/]|\\[cp]\b))/$1$2 ${1}emptydescription\n/g' $(git ls-files '*.[hc]' '*.function' '*.jinja')
```
i.e. add an `\emptydescription` argument to `\retval` commands (or
`@retval`, which we don't normally used) that are followed by a single word,
unless the next line looks like it contains text which would be the
description.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/include/psa/crypto_se_driver.h b/include/psa/crypto_se_driver.h
index bffebdd..e2acb71 100644
--- a/include/psa/crypto_se_driver.h
+++ b/include/psa/crypto_se_driver.h
@@ -384,8 +384,8 @@
* \param[in] direction Indicates whether the operation is an encrypt
* or decrypt
*
- * \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \retval #PSA_SUCCESS \emptydescription
+ * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
*/
typedef psa_status_t (*psa_drv_se_cipher_setup_t)(psa_drv_se_context_t *drv_context,
void *op_context,
@@ -406,7 +406,7 @@
* \param[in] p_iv A buffer containing the initialization vector
* \param[in] iv_length The size (in bytes) of the `p_iv` buffer
*
- * \retval #PSA_SUCCESS
+ * \retval #PSA_SUCCESS \emptydescription
*/
typedef psa_status_t (*psa_drv_se_cipher_set_iv_t)(void *op_context,
const uint8_t *p_iv,
@@ -428,7 +428,7 @@
* \param[out] p_output_length After completion, will contain the number
* of bytes placed in the `p_output` buffer
*
- * \retval #PSA_SUCCESS
+ * \retval #PSA_SUCCESS \emptydescription
*/
typedef psa_status_t (*psa_drv_se_cipher_update_t)(void *op_context,
const uint8_t *p_input,
@@ -449,7 +449,7 @@
* \param[out] p_output_length After completion, will contain the number of
* bytes placed in the `p_output` buffer
*
- * \retval #PSA_SUCCESS
+ * \retval #PSA_SUCCESS \emptydescription
*/
typedef psa_status_t (*psa_drv_se_cipher_finish_t)(void *op_context,
uint8_t *p_output,
@@ -484,8 +484,8 @@
* \param[in] output_size The allocated size in bytes of the `p_output`
* buffer
*
- * \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_NOT_SUPPORTED
+ * \retval #PSA_SUCCESS \emptydescription
+ * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
*/
typedef psa_status_t (*psa_drv_se_cipher_ecb_t)(psa_drv_se_context_t *drv_context,
psa_key_slot_number_t key_slot,
@@ -553,7 +553,7 @@
* \param[out] p_signature_length On success, the number of bytes
* that make up the returned signature value
*
- * \retval #PSA_SUCCESS
+ * \retval #PSA_SUCCESS \emptydescription
*/
typedef psa_status_t (*psa_drv_se_asymmetric_sign_t)(psa_drv_se_context_t *drv_context,
psa_key_slot_number_t key_slot,
@@ -617,7 +617,7 @@
* \param[out] p_output_length On success, the number of bytes that make up
* the returned output
*
- * \retval #PSA_SUCCESS
+ * \retval #PSA_SUCCESS \emptydescription
*/
typedef psa_status_t (*psa_drv_se_asymmetric_encrypt_t)(psa_drv_se_context_t *drv_context,
psa_key_slot_number_t key_slot,
@@ -657,7 +657,7 @@
* \param[out] p_output_length On success, the number of bytes
* that make up the returned output
*
- * \retval #PSA_SUCCESS
+ * \retval #PSA_SUCCESS \emptydescription
*/
typedef psa_status_t (*psa_drv_se_asymmetric_decrypt_t)(psa_drv_se_context_t *drv_context,
psa_key_slot_number_t key_slot,
@@ -903,8 +903,8 @@
* Success.
* The core will record \c *key_slot as the key slot where the key
* is stored and will update the persistent data in storage.
- * \retval #PSA_ERROR_NOT_SUPPORTED
- * \retval #PSA_ERROR_INSUFFICIENT_STORAGE
+ * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
+ * \retval #PSA_ERROR_INSUFFICIENT_STORAGE \emptydescription
*/
typedef psa_status_t (*psa_drv_se_allocate_key_t)(
psa_drv_se_context_t *drv_context,
@@ -1042,13 +1042,13 @@
* \param[out] p_data_length On success, the number of bytes
* that make up the key data.
*
- * \retval #PSA_SUCCESS
- * \retval #PSA_ERROR_DOES_NOT_EXIST
- * \retval #PSA_ERROR_NOT_PERMITTED
- * \retval #PSA_ERROR_NOT_SUPPORTED
- * \retval #PSA_ERROR_COMMUNICATION_FAILURE
- * \retval #PSA_ERROR_HARDWARE_FAILURE
- * \retval #PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_SUCCESS \emptydescription
+ * \retval #PSA_ERROR_DOES_NOT_EXIST \emptydescription
+ * \retval #PSA_ERROR_NOT_PERMITTED \emptydescription
+ * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
+ * \retval #PSA_ERROR_HARDWARE_FAILURE \emptydescription
+ * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
*/
typedef psa_status_t (*psa_drv_se_export_key_t)(psa_drv_se_context_t *drv_context,
psa_key_slot_number_t key,
@@ -1195,7 +1195,7 @@
* \param[in] source_key The key to be used as the source material for
* the key derivation
*
- * \retval #PSA_SUCCESS
+ * \retval #PSA_SUCCESS \emptydescription
*/
typedef psa_status_t (*psa_drv_se_key_derivation_setup_t)(psa_drv_se_context_t *drv_context,
void *op_context,
@@ -1215,7 +1215,7 @@
* \param[in] p_collateral A buffer containing the collateral data
* \param[in] collateral_size The size in bytes of the collateral
*
- * \retval #PSA_SUCCESS
+ * \retval #PSA_SUCCESS \emptydescription
*/
typedef psa_status_t (*psa_drv_se_key_derivation_collateral_t)(void *op_context,
uint32_t collateral_id,
@@ -1230,7 +1230,7 @@
* \param[in] dest_key The slot where the generated key material
* should be placed
*
- * \retval #PSA_SUCCESS
+ * \retval #PSA_SUCCESS \emptydescription
*/
typedef psa_status_t (*psa_drv_se_key_derivation_derive_t)(void *op_context,
psa_key_slot_number_t dest_key);
@@ -1244,7 +1244,7 @@
* \param[out] p_output_length Upon success, contains the number of bytes of
* key material placed in `p_output`
*
- * \retval #PSA_SUCCESS
+ * \retval #PSA_SUCCESS \emptydescription
*/
typedef psa_status_t (*psa_drv_se_key_derivation_export_t)(void *op_context,
uint8_t *p_output,