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:
parent
c2ac8fe7d7
commit
6bcb31d6ce
1 changed files with 31 additions and 24 deletions
|
@ -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);
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue