drivers/periph_{i2c,spi}: fix doc on initialization

Both SPI and I2C peripheral drivers *MUST NOT* be initialized by the
application code / (non-peripheral) device driver, as this is done
automatically be default. Some peripheral drivers have a non-idempotent
initialization and initializing them twice will break things.

Sadly, the doc states the exact opposite.

This updates the documentation to match the implementation. In addition
the special case is pointed out of disabling the automatic
initialization during boot, in which case the app indeed has to do the
initialization.

Author: maribu

drivers/include/periph/i2c.h

@@ -23,9 +23,6 @@
  * this example does not check any return values...):
  *
  * @code{c}
- * // initialize the bus (this is normally done during boot time)
- * i2c_init(dev);
- * ...
  * // before accessing the bus, we need to acquire it
  * i2c_acquire(dev);
  * // next we write the register address, but create no STOP condition when done
@@ -40,9 +37,6 @@
  * 7-bit device addressing:
  *
  * @code{c}
- * // initialize the bus
- * i2c_init(dev);
- * ...
  * // first, acquire the shared bus again
  * i2c_acquire(dev);
  * // write the 16-bit register address to the device and prevent STOP condition
@@ -205,6 +199,11 @@ typedef enum {
  * The bus MUST not be acquired before initializing it, as this is handled
  * internally by the i2c_init function!
  *
+ * @warning     This function **MUST NOT** be called by the user unless you add
+ *              `DISABLE_MODULE += periph_init_i2c` to your `Makefile`. If you
+ *              do so, call this function before any call to `i2c_acquire()`,
+ *              and call no more than **once**.
+ *
  * @param[in] dev       the device to initialize
  */
 void i2c_init(i2c_t dev);

drivers/include/periph/spi.h

@@ -34,8 +34,9 @@
  * low-power mode to save energy.
  *
  * The SPI unit's initialization is split into 3 parts:
- * 1. `spi_init()` should be called once for each SPI unit defined by a board
- *    during system initialization.
+ * 1. The SPI buses are automatically initialized during boot according to the
+ *    specification in board's `periph_conf.h`. (The exact format depends on the
+ *    MCU used.) See @ref spi_init for details.
  * 2. `spi_init_cs()` should be called during device driver initialization, as
  *    each chip select pin/line is used uniquely by a specific device, i.e. chip
  *    select lines are no shared resource.
@@ -198,14 +199,17 @@ typedef enum {
  * MISO, MOSI, and CLK pins. After initialization, the given device should be
  * in power down state.
  *
- * This function is intended to be called by the board initialization code
- * during system startup to prepare the (shared) SPI device for further usage.
- * It uses the board specific initialization parameters as defined in the
- * board's `periph_conf.h`.
+ * This function is called internally during system startup to prepare the
+ * (shared) SPI device for further usage. It uses the board specific
+ * initialization parameters as defined in the board's `periph_conf.h`.
  *
  * Errors (e.g. invalid @p bus parameter) are not signaled through a return
  * value, but should be signaled using the assert() function internally.
  *
+ * @warning     This function **MUST NOT** be called by the user unless you add
+ *              `DISABLE_MODULE += periph_init_spi` to your `Makefile`. If you
+ *              do so, call this function before any call to `spi_acquire()`,
+ *              and call no more than **once**.
  * @note    This function MUST not be called more than once per bus!
  *
  * @param[in] bus       SPI device to initialize