spi: update doxygen usage

Update doxygen usage of `@retval` to specify the value for each case,
instead of a chain of logic from the one `@retval`.
https://www.doxygen.nl/manual/commands.html#cmdretval

Convert `@retval`'s that simply reference another function to `@return`.

Convert some custom notes to `@note`.

Signed-off-by: Jordan Yates <jordan.yates@data61.csiro.au>
This commit is contained in:
Jordan Yates 2021-08-02 19:59:32 +10:00 committed by Anas Nashif
commit 6bcb31d6ce

View file

@ -442,7 +442,7 @@ static inline bool spi_is_ready(const struct spi_dt_spec *spec)
/**
* @brief Read/write the specified amount of data from the SPI driver.
*
* Note: This function is synchronous.
* @note This function is synchronous.
*
* @param dev Pointer to the device structure for the driver instance
* @param config Pointer to a valid spi_config structure instance.
@ -453,9 +453,9 @@ static inline bool spi_is_ready(const struct spi_dt_spec *spec)
* @param rx_bufs Buffer array where data to be read will be written to,
* or NULL if none.
*
* @retval 0 If successful, negative errno code otherwise. In case of slave
* transaction: if successful it will return the amount of frames
* received, negative errno code otherwise.
* @retval frames Positive number of frames received in slave mode.
* @retval 0 If successful in master mode.
* @retval -errno Negative errno code on failure.
*/
__syscall int spi_transceive(const struct device *dev,
const struct spi_config *config,
@ -486,7 +486,7 @@ static inline int z_impl_spi_transceive(const struct device *dev,
* @param rx_bufs Buffer array where data to be read will be written to,
* or NULL if none.
*
* @retval a value from spi_transceive()
* @return a value from spi_transceive().
*/
static inline int spi_transceive_dt(const struct spi_dt_spec *spec,
const struct spi_buf_set *tx_bufs,
@ -498,7 +498,9 @@ static inline int spi_transceive_dt(const struct spi_dt_spec *spec,
/**
* @brief Read the specified amount of data from the SPI driver.
*
* Note: This function is synchronous.
* @note This function is synchronous.
*
* @note This function is an helper function calling spi_transceive.
*
* @param dev Pointer to the device structure for the driver instance
* @param config Pointer to a valid spi_config structure instance.
@ -506,9 +508,8 @@ static inline int spi_transceive_dt(const struct spi_dt_spec *spec,
* previous operations.
* @param rx_bufs Buffer array where data to be read will be written to.
*
* @retval 0 If successful, negative errno code otherwise.
*
* @note This function is an helper function calling spi_transceive.
* @retval 0 If successful.
* @retval -errno Negative errno code on failure.
*/
static inline int spi_read(const struct device *dev,
const struct spi_config *config,
@ -527,7 +528,7 @@ static inline int spi_read(const struct device *dev,
* @param spec SPI specification from devicetree
* @param rx_bufs Buffer array where data to be read will be written to.
*
* @retval a value from spi_read()
* @return a value from spi_read().
*/
static inline int spi_read_dt(const struct spi_dt_spec *spec,
const struct spi_buf_set *rx_bufs)
@ -538,7 +539,9 @@ static inline int spi_read_dt(const struct spi_dt_spec *spec,
/**
* @brief Write the specified amount of data from the SPI driver.
*
* Note: This function is synchronous.
* @note This function is synchronous.
*
* @note This function is an helper function calling spi_transceive.
*
* @param dev Pointer to the device structure for the driver instance
* @param config Pointer to a valid spi_config structure instance.
@ -546,9 +549,8 @@ static inline int spi_read_dt(const struct spi_dt_spec *spec,
* previous operations.
* @param tx_bufs Buffer array where data to be sent originates from.
*
* @retval 0 If successful, negative errno code otherwise.
*
* @note This function is an helper function calling spi_transceive.
* @retval 0 If successful.
* @retval -errno Negative errno code on failure.
*/
static inline int spi_write(const struct device *dev,
const struct spi_config *config,
@ -567,7 +569,7 @@ static inline int spi_write(const struct device *dev,
* @param spec SPI specification from devicetree
* @param tx_bufs Buffer array where data to be sent originates from.
*
* @retval a value from spi_write()
* @return a value from spi_write().
*/
static inline int spi_write_dt(const struct spi_dt_spec *spec,
const struct spi_buf_set *tx_bufs)
@ -599,9 +601,9 @@ static inline int spi_write_dt(const struct spi_dt_spec *spec,
* notify the end of the transaction, and whether it went
* successfully or not).
*
* @retval 0 If successful, negative errno code otherwise. In case of slave
* transaction: if successful it will return the amount of frames
* received, negative errno code otherwise.
* @retval frames Positive number of frames received in slave mode.
* @retval 0 If successful in master mode.
* @retval -errno Negative errno code on failure.
*/
static inline int spi_transceive_async(const struct device *dev,
const struct spi_config *config,
@ -620,6 +622,8 @@ static inline int spi_transceive_async(const struct device *dev,
*
* @note This function is asynchronous.
*
* @note This function is an helper function calling spi_transceive_async.
*
* @note This function is available only if @kconfig{CONFIG_SPI_ASYNC}
* is selected.
*
@ -633,9 +637,8 @@ static inline int spi_transceive_async(const struct device *dev,
* notify the end of the transaction, and whether it went
* successfully or not).
*
* @retval 0 If successful, negative errno code otherwise.
*
* @note This function is an helper function calling spi_transceive_async.
* @retval 0 If successful
* @retval -errno Negative errno code on failure.
*/
static inline int spi_read_async(const struct device *dev,
const struct spi_config *config,
@ -650,6 +653,8 @@ static inline int spi_read_async(const struct device *dev,
*
* @note This function is asynchronous.
*
* @note This function is an helper function calling spi_transceive_async.
*
* @note This function is available only if @kconfig{CONFIG_SPI_ASYNC}
* is selected.
*
@ -663,9 +668,8 @@ static inline int spi_read_async(const struct device *dev,
* notify the end of the transaction, and whether it went
* successfully or not).
*
* @retval 0 If successful, negative errno code otherwise.
*
* @note This function is an helper function calling spi_transceive_async.
* @retval 0 If successful.
* @retval -errno Negative errno code on failure.
*/
static inline int spi_write_async(const struct device *dev,
const struct spi_config *config,
@ -690,6 +694,9 @@ static inline int spi_write_async(const struct device *dev,
* @param config Pointer to a valid spi_config structure instance.
* Pointer-comparison may be used to detect changes from
* previous operations.
*
* @retval 0 If successful.
* @retval -errno Negative errno code on failure.
*/
__syscall int spi_release(const struct device *dev,
const struct spi_config *config);