spi: update doxygen usage
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 <d74a90e280bbad1cc3646781a4e234b467b60fe1@data61.csiro.au>

galak/zephyr,zephyrproject-rtos/zephyr,finikorg/zephyr,finikorg/zephyr,zephyrproject-rtos/zephyr,galak/zephyr,zephyrproject-rtos/zephyr,zephyrproject-rtos/zephyr,finikorg/zephyr,galak/zephyr,zephyrproject-rtos/zephyr,finikorg/zephyr,galak/zephyr,galak/zephyr,finikorg/zephyr