SPI: More MR issues fixed, style fixup

components/driver/include/driver/spi_common.h

@@ -169,16 +169,6 @@ spi_dev_t *spicommon_hw_for_host(spi_host_device_t host);
 int spicommon_irqsource_for_host(spi_host_device_t host);
 
 
-/**
- * @note In some (well-defined) cases in the ESP32 (at least rev v.0 and v.1), a SPI DMA channel will get confused. This can be remedied
- * by resetting the SPI DMA hardware in case this happens. Unfortunately, the reset knob used for thsi will reset _both_ DMA channels, and
- * as such can only done safely when both DMA channels are idle. These functions coordinate this.
- * 
- * Essentially, when a reset is needed, a driver can request this using spicommon_dmaworkaround_req_reset. This is supposed to be called
- * with an user-supplied function as an argument. If both DMA channels are idle, this call will reset the DMA subsystem and return true. 
- * If the other DMA channel is still busy, it will return false; as soon as the other DMA channel is done, however, it will reset the 
- * DMA subsystem and call the callback. The callback is then supposed to be used to continue the SPI drivers activity.
-*/
 
 
 /**
@@ -190,6 +180,15 @@ typedef void(*dmaworkaround_cb_t)(void *arg);
 /**
  * @brief Request a reset for a certain DMA channel
  *
+ * @note In some (well-defined) cases in the ESP32 (at least rev v.0 and v.1), a SPI DMA channel will get confused. This can be remedied
+ * by resetting the SPI DMA hardware in case this happens. Unfortunately, the reset knob used for thsi will reset _both_ DMA channels, and
+ * as such can only done safely when both DMA channels are idle. These functions coordinate this.
+ * 
+ * Essentially, when a reset is needed, a driver can request this using spicommon_dmaworkaround_req_reset. This is supposed to be called
+ * with an user-supplied function as an argument. If both DMA channels are idle, this call will reset the DMA subsystem and return true. 
+ * If the other DMA channel is still busy, it will return false; as soon as the other DMA channel is done, however, it will reset the 
+ * DMA subsystem and call the callback. The callback is then supposed to be used to continue the SPI drivers activity.
+ *
  * @param dmachan DMA channel associated with the SPI host that needs a reset
  * @param cb Callback to call in case DMA channel cannot be reset immediately
  * @param arg Argument to the callback

components/driver/include/driver/spi_master.h

@@ -31,7 +31,7 @@ extern "C"
 #define SPI_DEVICE_TXBIT_LSBFIRST          (1<<0)  ///< Transmit command/address/data LSB first instead of the default MSB first
 #define SPI_DEVICE_RXBIT_LSBFIRST          (1<<1)  ///< Receive data LSB first instead of the default MSB first
 #define SPI_DEVICE_BIT_LSBFIRST            (SPI_TXBIT_LSBFIRST|SPI_RXBIT_LSBFIRST); ///< Transmit and receive LSB first
-#define SPI_DEVICE_3WIRE                   (1<<2)  ///< Use spid for both sending and receiving data
+#define SPI_DEVICE_3WIRE                   (1<<2)  ///< Use MOSI (=spid) for both sending and receiving data
 #define SPI_DEVICE_POSITIVE_CS             (1<<3)  ///< Make CS positive during a transaction instead of negative
 #define SPI_DEVICE_HALFDUPLEX              (1<<4)  ///< Transmit data before receiving it, instead of simultaneously
 #define SPI_DEVICE_CLK_AS_CS               (1<<5)  ///< Output clock on CS line if CS is active

components/driver/include/driver/spi_slave.h

@@ -59,7 +59,7 @@ struct spi_slave_transaction_t {
 };
 
 /**
- * @brief Initialize a SPI bus
+ * @brief Initialize a SPI bus as a slave interface
  *
  * @warning For now, only supports HSPI and VSPI.
  *
@@ -92,10 +92,13 @@ esp_err_t spi_slave_free(spi_host_device_t host);
 /**
  * @brief Queue a SPI transaction for execution
  *
- * This will queue a transaction for the master to pick it up. If the queue (specified in ``spi_slave_initialize``)
- * is not full, this function will return directly; the actual transaction will be done if there aren't any
- * unhandled transactions before it and the master initiates a SPI transaction by pulling down CS and sending out
- * clock signals.
+ * Queues a SPI transaction to be executed by this slave device. (The transaction queue size was specified when the slave
+ * device was initialised via spi_slave_initialize.) This function may block if the queue is full (depending on the
+ * ticks_to_wait parameter). No SPI operation is directly initiated by this function, the next queued transaction
+ * will happen when the master initiates a SPI transaction by pulling down CS and sending out clock signals.
+ *
+ * This function hands over ownership of the buffers in ``trans_desc`` to the SPI slave driver; the application is
+ * not to access this memory until ``spi_slave_queue_trans`` is called to hand ownership back to the application.
  *
  * @param host SPI peripheral that is acting as a slave
  * @param trans_desc Description of transaction to execute. Not const because we may want to write status back
@@ -117,8 +120,10 @@ esp_err_t spi_slave_queue_trans(spi_host_device_t host, const spi_slave_transact
  * completed transaction so software can inspect the result and e.g. free the memory or 
  * re-use the buffers.
  *
+ * It is mandatory to eventually use this function for any transaction queued by ``spi_slave_queue_trans``.
+ *
  * @param host SPI peripheral to that is acting as a slave
- * @param trans_desc Pointer to variable able to contain a pointer to the description of the 
+ * @param[out] trans_desc Pointer to variable able to contain a pointer to the description of the 
  *                   transaction that is executed
  * @param ticks_to_wait Ticks to wait until there's a returned item; use portMAX_DELAY to never time
  *                      out.