diff --git a/src/rp2_common/hardware_flash/include/hardware/flash.h b/src/rp2_common/hardware_flash/include/hardware/flash.h
index 5fbf0c7b..eb132d19 100644
--- a/src/rp2_common/hardware_flash/include/hardware/flash.h
+++ b/src/rp2_common/hardware_flash/include/hardware/flash.h
@@ -56,6 +56,10 @@ extern "C" {
  *
  * \param flash_offs Offset into flash, in bytes, to start the erase. Must be aligned to a 4096-byte flash sector.
  * \param count Number of bytes to be erased. Must be a multiple of 4096 bytes (one sector).
+ *
+ * @note Erasing a flash sector sets all the bits in all the pages in that sector to one.
+ * You can then "program" flash pages in the sector to turn some of the bits to zero.
+ * Once a bit is set to zero it can only be changed back to one by erasing the whole sector again.
  */
 void flash_range_erase(uint32_t flash_offs, size_t count);
 
@@ -65,6 +69,10 @@ void flash_range_erase(uint32_t flash_offs, size_t count);
  * \param flash_offs Flash address of the first byte to be programmed. Must be aligned to a 256-byte flash page.
  * \param data Pointer to the data to program into flash
  * \param count Number of bytes to program. Must be a multiple of 256 bytes (one page).
+ *
+ * @note: Programming a flash page effectively changes some of the bits from one to zero.
+ * The only way to change a zero bit back to one is to "erase" the whole sector that the page resides in.
+ * So you may need to make sure you have called flash_range_erase before calling flash_range_program.
  */
 
 void flash_range_program(uint32_t flash_offs, const uint8_t *data, size_t count);
diff --git a/src/rp2_common/hardware_uart/include/hardware/uart.h b/src/rp2_common/hardware_uart/include/hardware/uart.h
index 12d6a145..5e4e3ea3 100644
--- a/src/rp2_common/hardware_uart/include/hardware/uart.h
+++ b/src/rp2_common/hardware_uart/include/hardware/uart.h
@@ -56,13 +56,14 @@ extern "C" {
  *  \code
  *  int main() {
  *
- *     // Initialise UART 0
- *     uart_init(uart0, 115200);
- *
  *     // Set the GPIO pin mux to the UART - 0 is TX, 1 is RX
+ *     // Do this before calling uart_init to avoid losing data
  *     gpio_set_function(0, GPIO_FUNC_UART);
  *     gpio_set_function(1, GPIO_FUNC_UART);
  *
+ *     // Initialise UART 0
+ *     uart_init(uart0, 115200);
+ *
  *     uart_puts(uart0, "Hello world!");
  * }
  * \endcode
@@ -310,7 +311,7 @@ static inline bool uart_is_readable(uart_inst_t *uart) {
 /*! \brief  Write to the UART for transmission.
  *  \ingroup hardware_uart
  *
- * This function will block until all the data has been sent to the UART
+ * This function will block until all the data has been sent to the UART transmit buffer
  *
  * \param uart UART instance. \ref uart0 or \ref uart1
  * \param src The bytes to send
@@ -347,7 +348,7 @@ static inline void uart_read_blocking(uart_inst_t *uart, uint8_t *dst, size_t le
 /*! \brief  Write single character to UART for transmission.
  *  \ingroup hardware_uart
  *
- * This function will block until the entire character has been sent
+ * This function will block until the entire character has been sent to the UART transmit buffer
  *
  * \param uart UART instance. \ref uart0 or \ref uart1
  * \param c The character  to send
@@ -359,7 +360,7 @@ static inline void uart_putc_raw(uart_inst_t *uart, char c) {
 /*! \brief  Write single character to UART for transmission, with optional CR/LF conversions
  *  \ingroup hardware_uart
  *
- * This function will block until the character has been sent
+ * This function will block until the character has been sent to the UART transmit buffer
  *
  * \param uart UART instance. \ref uart0 or \ref uart1
  * \param c The character  to send
@@ -376,7 +377,7 @@ static inline void uart_putc(uart_inst_t *uart, char c) {
 /*! \brief  Write string to UART for transmission, doing any CR/LF conversions
  *  \ingroup hardware_uart
  *
- * This function will block until the entire string has been sent
+ * This function will block until the entire string has been sent to the UART transmit buffer
  *
  * \param uart UART instance. \ref uart0 or \ref uart1
  * \param s The null terminated string to send