docs: Ensure Doxygen return values use references

At present a lot of the code-base uses `\retval` commands to framework
status codes but does not explicitly link to them. In some cases it's
necessary to explicitly link to these status codes to have Doxygen
generate a link to the relevant enumeration, and we can do this by
prefixing the name with `::`.

This style is already used in much of the code-base, so should not
conflict with any existing styles.

Change-Id: Ifc78eb425981bee3a01c791757a41a61c20e636c
Signed-off-by: Chris Kay <chris.kay@arm.com>

4 files changed, 36 insertions, 36 deletions

diff --git a/product/morello/module/cmn_skeena/include/mod_cmn_skeena.h b/product/morello/module/cmn_skeena/include/mod_cmn_skeena.h
index e409af63..dbfd5431 100644
--- a/product/morello/module/cmn_skeena/include/mod_cmn_skeena.h
+++ b/product/morello/module/cmn_skeena/include/mod_cmn_skeena.h
@@ -258,7 +258,7 @@ struct mod_cmn_skeena_ccix_config_api {
      *
      * \param[out] config CCIX host configuration
      *
-     * \retval FWK_SUCCESS if the operation succeed.
+     * \retval ::FWK_SUCCESS if the operation succeed.
      * \return one of the error code otherwise.
      */
     int (*get_config)(struct mod_cmn_skeena_ccix_host_node_config *config);
@@ -267,7 +267,7 @@ struct mod_cmn_skeena_ccix_config_api {
      *
      * \param[in] config CCIX endpoint configuration
      *
-     * \retval FWK_SUCCESS if the operation succeed.
+     * \retval ::FWK_SUCCESS if the operation succeed.
      * \return one of the error code otherwise.
      */
     int (*set_config)(struct mod_cmn_skeena_ccix_remote_node_config *config);
@@ -277,7 +277,7 @@ struct mod_cmn_skeena_ccix_config_api {
      * \param  link_id Link on which the protocol credit exchange
      *                 would initiate.
      *
-     * \retval FWK_SUCCESS if the operation succeed.
+     * \retval ::FWK_SUCCESS if the operation succeed.
      * \return one of the error code otherwise.
      */
     int (*exchange_protocol_credit)(uint8_t link_id);
@@ -287,7 +287,7 @@ struct mod_cmn_skeena_ccix_config_api {
      * \param  link_id Link on which the coherency has to
      *                 be enabled.
      *
-     * \retval FWK_SUCCESS if the operation succeed.
+     * \retval ::FWK_SUCCESS if the operation succeed.
      * \return one of the error code otherwise.
      */
     int (*enter_system_coherency)(uint8_t link_id);
@@ -296,7 +296,7 @@ struct mod_cmn_skeena_ccix_config_api {
      *
      * \param  link_id Link on which DVM domain has to be enabled
      *
-     * \retval FWK_SUCCESS if the operation succeed.
+     * \retval ::FWK_SUCCESS if the operation succeed.
      * \return one of the error code otherwise.
      */
     int (*enter_dvm_domain)(uint8_t link_id);
diff --git a/product/morello/module/dmc_bing/include/mod_dmc_bing.h b/product/morello/module/dmc_bing/include/mod_dmc_bing.h
index 58888063..a87dd0cc 100644
--- a/product/morello/module/dmc_bing/include/mod_dmc_bing.h
+++ b/product/morello/module/dmc_bing/include/mod_dmc_bing.h
@@ -637,7 +637,7 @@ struct mod_dmc_ddr_phy_api {
      * \param element_id Element identifier corresponding to the device to
      *      configure.
      *
-     * \retval FWK_SUCCESS if the operation succeed.
+     * \retval ::FWK_SUCCESS if the operation succeed.
      * \return one of the error code otherwise.
      */
     int (*configure)(fwk_id_t element_id);
diff --git a/product/morello/module/morello_smt/include/mod_smt.h b/product/morello/module/morello_smt/include/mod_smt.h
index dd4e2dc1..d3e2de62 100644
--- a/product/morello/module/morello_smt/include/mod_smt.h
+++ b/product/morello/module/morello_smt/include/mod_smt.h
@@ -104,8 +104,8 @@ struct mod_smt_driver_api {
      *
      * \param device_id Device identifier
      *
-     * \retval FWK_SUCCESS The operation succeeded
-     * \retval FWK_E_PARAM The device_id parameter is invalid
+     * \retval ::FWK_SUCCESS The operation succeeded
+     * \retval ::FWK_E_PARAM The device_id parameter is invalid
      * \return One of the standard error codes for implementation-defined
      * errors
      */
@@ -123,7 +123,7 @@ struct mod_smt_driver_input_api {
      *
      * \param device_id Channel identifier
      *
-     * \retval FWK_SUCCESS The operation succeeded.
+     * \retval ::FWK_SUCCESS The operation succeeded.
      * \return One of the standard error codes for implementation-defined
      * errors.
      */
@@ -141,9 +141,9 @@ struct mod_scmi_to_transport_api {
      * \param[out] secure The channel security state. True
      * if the channel is secure, or false if it is non-secure.
      *
-     * \retval FWK_SUCCESS The operation succeeded.
-     * \retval FWK_E_PARAM The channel_id parameter is invalid.
-     * \retval FWK_E_PARAM The secure parameter is NULL.
+     * \retval ::FWK_SUCCESS The operation succeeded.
+     * \retval ::FWK_E_PARAM The channel_id parameter is invalid.
+     * \retval ::FWK_E_PARAM The secure parameter is NULL.
      * \return One of the standard error codes for implementation-defined
      * errors.
      */
@@ -155,9 +155,9 @@ struct mod_scmi_to_transport_api {
      * \param channel_id Channel identifier.
      * \param[out] size The maximum payload size in bytes.
      *
-     * \retval FWK_SUCCESS The operation succeeded.
-     * \retval FWK_E_PARAM The channel_id parameter is invalid.
-     * \retval FWK_E_PARAM The size parameter is NULL.
+     * \retval ::FWK_SUCCESS The operation succeeded.
+     * \retval ::FWK_E_PARAM The channel_id parameter is invalid.
+     * \retval ::FWK_E_PARAM The size parameter is NULL.
      * \return One of the standard error codes for implementation-defined
      * errors.
      */
@@ -169,10 +169,10 @@ struct mod_scmi_to_transport_api {
      * \param channel_id Channel identifier.
      * \param[out] message_header The SCMI message header.
      *
-     * \retval FWK_SUCCESS The operation succeeded.
-     * \retval FWK_E_PARAM The channel_id parameter is invalid.
-     * \retval FWK_E_PARAM The message_header parameter is NULL.
-     * \retval FWK_E_ACCESS No message is available to read.
+     * \retval ::FWK_SUCCESS The operation succeeded.
+     * \retval ::FWK_E_PARAM The channel_id parameter is invalid.
+     * \retval ::FWK_E_PARAM The message_header parameter is NULL.
+     * \retval ::FWK_E_ACCESS No message is available to read.
      * \return One of the standard error codes for implementation-defined
      * errors.
      */
@@ -186,10 +186,10 @@ struct mod_scmi_to_transport_api {
      * \param[out] size The payload size. May be NULL, in which case the
      * parameter should be ignored.
      *
-     * \retval FWK_SUCCESS The operation succeeded.
-     * \retval FWK_E_PARAM The channel_id parameter is invalid.
-     * \retval FWK_E_PARAM The payload parameter is NULL.
-     * \retval FWK_E_ACCESS No message is available to read.
+     * \retval ::FWK_SUCCESS The operation succeeded.
+     * \retval ::FWK_E_PARAM The channel_id parameter is invalid.
+     * \retval ::FWK_E_PARAM The payload parameter is NULL.
+     * \retval ::FWK_E_ACCESS No message is available to read.
      * \return One of the standard error codes for implementation-defined
      * errors.
      */
@@ -203,9 +203,9 @@ struct mod_scmi_to_transport_api {
      * \param payload Payload data to write.
      * \param size Size of the payload data.
      *
-     * \retval FWK_SUCCESS The operation succeeded.
-     * \retval FWK_E_PARAM The payload parameter is NULL.
-     * \retval FWK_E_PARAM The offset and size provided are not within the
+     * \retval ::FWK_SUCCESS The operation succeeded.
+     * \retval ::FWK_E_PARAM The payload parameter is NULL.
+     * \retval ::FWK_E_PARAM The offset and size provided are not within the
      * bounds of the payload area.
      * \return One of the standard error codes for implementation-defined
      * errors.
@@ -224,11 +224,11 @@ struct mod_scmi_to_transport_api {
      * been written.
      * \param size Size of the payload source.
      *
-     * \retval FWK_SUCCESS The operation succeeded.
-     * \retval FWK_E_PARAM The channel_id parameter is invalid.
-     * \retval FWK_E_PARAM The size parameter is less than the size of one
+     * \retval ::FWK_SUCCESS The operation succeeded.
+     * \retval ::FWK_E_PARAM The channel_id parameter is invalid.
+     * \retval ::FWK_E_PARAM The size parameter is less than the size of one
      * payload entry.
-     * \retval FWK_E_ACCESS No message is available to respond to.
+     * \retval ::FWK_E_ACCESS No message is available to respond to.
      * \return One of the standard error codes for implementation-defined
      * errors.
      */
@@ -257,7 +257,7 @@ struct mod_scmi_agent_to_transport_api {
      * \param channel_id Channel identifier
      * \param cmd Pointer to SMT command configuration
      *
-     * \retval FWK_SUCCESS The operation succeeded.
+     * \retval ::FWK_SUCCESS The operation succeeded.
      * \return One of the standard error codes for implementation-defined
      * errors.
      */
@@ -271,7 +271,7 @@ struct mod_scmi_agent_to_transport_api {
      * \param[out] size The payload size. May be NULL, in which case the
      * parameter should be ignored.
      *
-     * \retval FWK_SUCCESS The operation succeeded.
+     * \retval ::FWK_SUCCESS The operation succeeded.
      * \return One of the standard error codes for implementation-defined
      * errors.
      */
@@ -282,7 +282,7 @@ struct mod_scmi_agent_to_transport_api {
      *
      * \param channel_id Channel identifier
      *
-     * \retval FWK_SUCCESS The operation succeeded.
+     * \retval ::FWK_SUCCESS The operation succeeded.
      * \return One of the standard error codes for implementation-defined
      * errors.
      */
diff --git a/product/morello/module/scmi_agent/include/mod_scmi_agent.h b/product/morello/module/scmi_agent/include/mod_scmi_agent.h
index f93c9a61..1c243fcc 100644
--- a/product/morello/module/scmi_agent/include/mod_scmi_agent.h
+++ b/product/morello/module/scmi_agent/include/mod_scmi_agent.h
@@ -77,7 +77,7 @@ struct mod_scmi_agent_api {
      * \param agent_id Agent identifier
      * \param[out] version Protocol version.
      *
-     * \retval FWK_SUCCESS The operation succeeded.
+     * \retval ::FWK_SUCCESS The operation succeeded.
      * \return One of the standard error codes for implementation-defined
      * errors.
      */
@@ -89,7 +89,7 @@ struct mod_scmi_agent_api {
      * \param agent_id Agent identifier
      * \param[out] clock_status SCP clock status.
      *
-     * \retval FWK_SUCCESS The operation succeeded.
+     * \retval ::FWK_SUCCESS The operation succeeded.
      * \return One of the standard error codes for implementation-defined
      * errors.
      */
@@ -102,7 +102,7 @@ struct mod_scmi_agent_api {
      * \param[out] multichip_mode Multi-chip mode value.
      * \param[out] chipid Chip ID value.
      *
-     * \retval FWK_SUCCESS The operation succeeded.
+     * \retval ::FWK_SUCCESS The operation succeeded.
      * \return One of the standard error codes for implementation-defined
      * errors.
      */