Some doc issues (#1772)
* Fix doxygen for uart example
Fixes https://github.com/raspberrypi/pico-sdk/issues/1685
* Clarify uart write
will block until data "has been sent to the UART transmit buffer"
Fixes https://github.com/raspberrypi/pico-sdk/issues/1481
* Add note to flash API about erasing sectors
Fixes: https://github.com/raspberrypi/pico-sdk/issues/650
diff --git a/src/rp2_common/hardware_flash/include/hardware/flash.h b/src/rp2_common/hardware_flash/include/hardware/flash.h
index 5fbf0c7..eb132d1 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 @@
*
* \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 @@
* \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 12d6a14..5e4e3ea 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 @@
* \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 @@
/*! \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 @@
/*! \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 @@
/*! \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 @@
/*! \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
