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 a052789..9ae631f 100644
--- a/include/psa/crypto_se_driver.h
+++ b/include/psa/crypto_se_driver.h
@@ -385,8 +385,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,
@@ -407,7 +407,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,
@@ -429,7 +429,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,
@@ -450,7 +450,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,
@@ -485,8 +485,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,
@@ -554,7 +554,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,
@@ -618,7 +618,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,
@@ -658,7 +658,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,
@@ -904,8 +904,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,
@@ -1043,13 +1043,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,
@@ -1196,7 +1196,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,
@@ -1216,7 +1216,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,
@@ -1231,7 +1231,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);
@@ -1245,7 +1245,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,