drivers/periph/spi: clean up error codes and doc

- Use negative errno as error codes, rather than home-grown enums
    - Update the home-grown enum with negative errno codes for backward
      compatibility and mark it deprecated
- Update API doc to use negative errno codes
- Fix various style issues in Doxygen doc
    - Use `@retval` to document specific return values instead of abusing
      `@return` for this
    - Align parameters to proper indent level

drivers/include/periph/spi.h

@@ -66,10 +66,11 @@
 #ifndef PERIPH_SPI_H
 #define PERIPH_SPI_H
 
+#include <errno.h>
+#include <limits.h>
 #include <stdbool.h>
 #include <stddef.h>
 #include <stdint.h>
-#include <limits.h>
 
 #include "periph_cpu.h"
 #include "periph_conf.h"
@@ -128,13 +129,16 @@ typedef gpio_t spi_cs_t;
 
 /**
  * @brief       Status codes used by the SPI driver interface
+ *
+ * @deprecated  Use negative errno codes instead. The enum is still provided
+ *              for backwards compatibility
  */
 enum {
     SPI_OK          =  0,       /**< everything went as planned */
-    SPI_NODEV       = -1,   /**< invalid SPI bus specified */
+    SPI_NODEV       = -ENXIO,   /**< invalid SPI bus specified */
-    SPI_NOCS        = -2,   /**< invalid chip select line specified */
+    SPI_NOCS        = -EINVAL,  /**< invalid chip select line specified */
-    SPI_NOMODE      = -3,   /**< selected mode is not supported */
+    SPI_NOMODE      = -EINVAL,  /**< selected mode is not supported */
-    SPI_NOCLK       = -4    /**< selected clock value is not supported */
+    SPI_NOCLK       = -EINVAL   /**< selected clock value is not supported */
 };
 
 /**
@@ -234,9 +238,9 @@ void spi_init_pins(spi_t bus);
  * @param[in]   bus     SPI device that is used with the given CS line
  * @param[in]   cs      chip select pin to initialize
  *
- * @return              SPI_OK on success
+ * @retval  0           success
- * @return              SPI_NODEV on invalid device
+ * @retval  -ENXIO      invalid device
- * @return              SPI_NOCS on invalid CS pin/line
+ * @retval  -EINVAL     invalid CS pin/line
  */
 int spi_init_cs(spi_t bus, spi_cs_t cs);
 
@@ -322,8 +326,8 @@ typedef struct {
  * @param[in]   bus     SPI device that is used with the given CS line
  * @param[in]   mode    a struct containing the 3 modes to use on each pin
  *
- * @return              0 on success
+ * @retval  0           success
- * @return              <0 on error
+ * @retval  <0          error
  */
 int spi_init_with_gpio_mode(spi_t bus, spi_gpio_mode_t mode);
 #endif
@@ -345,9 +349,11 @@ int spi_init_with_gpio_mode(spi_t bus, spi_gpio_mode_t mode);
  * @param[in]   mode    mode to use for the new transaction
  * @param[in]   clk     bus clock speed to use for the transaction
  *
- * @return              SPI_OK on success
+ * @retval  0           success
- * @return              SPI_NOMODE if given mode is not supported
+ * @return  -EINVAL     Invalid mode in @p mode
- * @return              SPI_NOCLK if given clock speed is not supported
+ * @return  -EINVAL     Invalid clock in @p clock
+ * @return  -ENOTSUP    Unsupported but valid mode in @p mode
+ * @return  -ENOTSUP    Unsupported but valid clock in @p clock
  */
 int spi_acquire(spi_t bus, spi_cs_t cs, spi_mode_t mode, spi_clk_t clk);