nrf_security: fix Doxygen issues

Headers had numerous Doxygen issues, this patch fixes all of them
so that Doxygen build is clean from warnings/errors.

Signed-off-by: Gerard Marull-Paretas <[email protected]>

Author: gmarull

subsys/nrf_security/include/crypto_compat.h

@@ -1,5 +1,5 @@
 /**
- * \file psa/crypto_compat.h
+ * \file crypto_compat.h
  *
  * \brief PSA cryptography module: Backward compatibility aliases
  *
@@ -46,12 +46,12 @@ static inline int psa_key_handle_is_null(psa_key_handle_t handle)
 /** Open a handle to an existing persistent key.
  *
  * Open a handle to a persistent key. A key is persistent if it was created
- * with a lifetime other than #PSA_KEY_LIFETIME_VOLATILE. A persistent key
+ * with a lifetime other than PSA_KEY_LIFETIME_VOLATILE. A persistent key
  * always has a nonzero key identifier, set with psa_set_key_id() when
  * creating the key. Implementations may provide additional pre-provisioned
  * keys that can be opened with psa_open_key(). Such keys have an application
  * key identifier in the vendor range, as documented in the description of
- * #psa_key_id_t.
+ * psa_key_id_t.
  *
  * The application must eventually close the handle with psa_close_key() or
  * psa_destroy_key() to release associated resources. If the application dies
@@ -93,11 +93,11 @@ static inline int psa_key_handle_is_null(psa_key_handle_t handle)
  *         permission to access it. Note that this specification does not
  *         define any way to create such a key, but it may be possible
  *         through implementation-specific means.
- * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
- * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
- * \retval #PSA_ERROR_STORAGE_FAILURE \emptydescription
- * \retval #PSA_ERROR_DATA_INVALID \emptydescription
- * \retval #PSA_ERROR_DATA_CORRUPT \emptydescription
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_CORRUPTION_DETECTED
+ * \retval #PSA_ERROR_STORAGE_FAILURE
+ * \retval PSA_ERROR_DATA_INVALID
+ * \retval #PSA_ERROR_DATA_CORRUPT
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -137,8 +137,8 @@ psa_status_t psa_open_key(mbedtls_svc_key_id_t key,
  *         \p handle was a valid handle or \c 0. It is now closed.
  * \retval #PSA_ERROR_INVALID_HANDLE
  *         \p handle is not a valid handle nor \c 0.
- * \retval #PSA_ERROR_COMMUNICATION_FAILURE \emptydescription
- * \retval #PSA_ERROR_CORRUPTION_DETECTED \emptydescription
+ * \retval #PSA_ERROR_COMMUNICATION_FAILURE
+ * \retval PSA_ERROR_CORRUPTION_DETECTED
  * \retval #PSA_ERROR_BAD_STATE
  *         The library has not been previously initialized by psa_crypto_init().
  *         It is implementation-dependent whether a failure to initialize
@@ -175,8 +175,8 @@ psa_status_t psa_close_key(psa_key_handle_t handle);
  * \param[in] data              Ignored.
  * \param data_length           Must be 0.
  *
- * \retval #PSA_SUCCESS \emptydescription
- * \retval #PSA_ERROR_NOT_SUPPORTED \emptydescription
+ * \retval #PSA_SUCCESS
+ * \retval #PSA_ERROR_NOT_SUPPORTED
  */
 static inline psa_status_t MBEDTLS_DEPRECATED psa_set_key_domain_parameters(
 	psa_key_attributes_t *attributes,
@@ -202,7 +202,7 @@ static inline psa_status_t MBEDTLS_DEPRECATED psa_set_key_domain_parameters(
  * \param data_size             Ignored.
  * \param[out] data_length      Set to 0.
  *
- * \retval #PSA_SUCCESS \emptydescription
+ * \retval #PSA_SUCCESS
  */
 static inline psa_status_t MBEDTLS_DEPRECATED psa_get_key_domain_parameters(
 	const psa_key_attributes_t *attributes,

subsys/nrf_security/include/psa/client.h

@@ -119,6 +119,10 @@ uint32_t psa_version(uint32_t sid);
 /**
  * \brief Connect to an RoT Service by its SID.
  *
+ * The call is invalid if one or more of the following are true:
+ * - The RoT Service ID is not present.
+ * - The RoT Service version is not supported.
+ * - The caller is not allowed to access the RoT service.
  * \param[in] sid               ID of the RoT Service to connect to.
  * \param[in] version           Requested version of the RoT Service.
  *
@@ -127,12 +131,6 @@ uint32_t psa_version(uint32_t sid);
  *                              connection.
  * \retval PSA_ERROR_CONNECTION_BUSY The SPM or RoT Service cannot make the
  *                              connection at the moment.
- * \retval "PROGRAMMER ERROR"   The call is a PROGRAMMER ERROR if one or more
- *                              of the following are true:
- * \arg                           The RoT Service ID is not present.
- * \arg                           The RoT Service version is not supported.
- * \arg                           The caller is not allowed to access the RoT
- *                                service.
  */
 psa_handle_t psa_connect(uint32_t sid, uint32_t version);
 
@@ -147,6 +145,14 @@ psa_handle_t psa_connect(uint32_t sid, uint32_t version);
  *        range has to be reduced into a 16-bit integer. So with this encoding,
  *        the valid range for 'type' is 0-32767.
  *
+ * The call is invalid if one or more of the following are true:
+ * - An invalid handle was passed.
+ * - The connection is already handling a request.
+ * - type < 0.
+ * - An invalid memory reference was provided.
+ * - in_len + out_len > PSA_MAX_IOVEC.
+ * - The message is unrecognized by the RoT Service or incorrectly formatted.
+ *
  * \param[in] handle            A handle to an established connection.
  * \param[in] type              The request type.
  *                              Must be zero( \ref PSA_IPC_CALL) or positive.
@@ -157,16 +163,6 @@ psa_handle_t psa_connect(uint32_t sid, uint32_t version);
  *
  * \retval >=0                  RoT Service-specific status value.
  * \retval <0                   RoT Service-specific error code.
- * \retval PSA_ERROR_PROGRAMMER_ERROR The connection has been terminated by the
- *                              RoT Service. The call is a PROGRAMMER ERROR if
- *                              one or more of the following are true:
- * \arg                           An invalid handle was passed.
- * \arg                           The connection is already handling a request.
- * \arg                           type < 0.
- * \arg                           An invalid memory reference was provided.
- * \arg                           in_len + out_len > PSA_MAX_IOVEC.
- * \arg                           The message is unrecognized by the RoT
- *                                Service or incorrectly formatted.
  */
 psa_status_t psa_call(psa_handle_t handle, int32_t type,
                       const psa_invec *in_vec,
@@ -177,16 +173,12 @@ psa_status_t psa_call(psa_handle_t handle, int32_t type,
 /**
  * \brief Close a connection to an RoT Service.
  *
+ * The call is invalid if one or more of the following are true:
+ * - An invalid handle was provided that is not the null handle.
+ * - The connection is currently handling a request.
+ *
  * \param[in] handle            A handle to an established connection, or the
  *                              null handle.
- *
- * \retval void                 Success.
- * \retval "PROGRAMMER ERROR"   The call is a PROGRAMMER ERROR if one or more
- *                              of the following are true:
- * \arg                           An invalid handle was provided that is not
- *                                the null handle.
- * \arg                           The connection is currently handling a
- *                                request.
  */
 void psa_close(psa_handle_t handle);