diff --git a/src/rp2_common/hardware_spi/include/hardware/spi.h b/src/rp2_common/hardware_spi/include/hardware/spi.h
index f0de5a3..3ee8736 100644
--- a/src/rp2_common/hardware_spi/include/hardware/spi.h
+++ b/src/rp2_common/hardware_spi/include/hardware/spi.h
@@ -252,6 +252,8 @@ int spi_read_blocking(spi_inst_t *spi, uint8_t repeated_tx_data, uint8_t *dst, s
  * Write \p len halfwords from \p src to SPI. Simultaneously read \p len halfwords from SPI to \p dst.
  * Blocks until all data is transferred. No timeout, as SPI hardware always transfers at a known data rate.
  *
+ * \note SPI should be initialised with 16 data_bits using \ref spi_set_format first, otherwise this function will only read/write 8 data_bits.
+ *
  * \param spi SPI instance specifier, either \ref spi0 or \ref spi1
  * \param src Buffer of data to write
  * \param dst Buffer for read data
@@ -266,6 +268,8 @@ int spi_write16_read16_blocking(spi_inst_t *spi, const uint16_t *src, uint16_t *
  * Write \p len halfwords from \p src to SPI. Discard any data received back.
  * Blocks until all data is transferred. No timeout, as SPI hardware always transfers at a known data rate.
  *
+ * \note SPI should be initialised with 16 data_bits using \ref spi_set_format first, otherwise this function will only write 8 data_bits.
+ *
  * \param spi SPI instance specifier, either \ref spi0 or \ref spi1
  * \param src Buffer of data to write
  * \param len Length of buffers
@@ -282,6 +286,8 @@ int spi_write16_blocking(spi_inst_t *spi, const uint16_t *src, size_t len);
  * Generally this can be 0, but some devices require a specific value here,
  * e.g. SD cards expect 0xff
  *
+ * \note SPI should be initialised with 16 data_bits using \ref spi_set_format first, otherwise this function will only read 8 data_bits.
+ *
  * \param spi SPI instance specifier, either \ref spi0 or \ref spi1
  * \param repeated_tx_data Buffer of data to write
  * \param dst Buffer for read data