add migration guide about deprecated API

RF24.h

@@ -873,6 +873,8 @@ class RF24
 
     /**
      * @deprecated Use RF24::isFifo(bool about_tx) instead.
+     * See our [migration guide](migration.md) to understand what you should update in your code.
+     *
      * @param about_tx `true` focuses on the TX FIFO, `false` focuses on the RX FIFO
      * @param check_empty
      * - `true` checks if the specified FIFO is empty
@@ -1897,7 +1899,8 @@ class RF24
     /**
      * Open a pipe for reading
      * @deprecated For compatibility with old code only, see newer function
-     * openReadingPipe()
+     * openReadingPipe().
+     * See our [migration guide](migration.md) to understand what you should update in your code.
      *
      * @note Pipes 1-5 should share the first 32 bits.
      * Only the least significant byte should be unique, e.g.
@@ -1922,7 +1925,8 @@ class RF24
     /**
      * Open a pipe for writing
      * @deprecated For compatibility with old code only, see newer function
-     * openWritingPipe()
+     * openWritingPipe().
+     * See our [migration guide](migration.md) to understand what you should update in your code.
      *
      * Addresses are 40-bit hex values, e.g.:
      *
@@ -1940,6 +1944,7 @@ class RF24
      *
      * @deprecated For compatibility with old code only, see synonymous function available().
      * Use read() to retrieve the ack payload and getDynamicPayloadSize() to get the ACK payload size.
+     * See our [migration guide](migration.md) to understand what you should update in your code.
      *
      * @return True if an ack payload is available.
      */
@@ -1950,6 +1955,7 @@ class RF24
      * Request (IRQ) pin active LOW.
      *
      * @deprecated Use setStatusFlags() instead.
+     * See our [migration guide](migration.md) to understand what you should update in your code.
      *
      * The following events can be configured:
      * 1. "data sent": This does not mean that the data transmitted was
@@ -1988,6 +1994,7 @@ class RF24
      * LOW and clears the status of all events.
      *
      * @deprecated Use clearStatusFlags() instead.
+     * See our [migration guide](migration.md) to understand what you should update in your code.
      *
      * @see setStatusFlags()
      *

docs/main_page.md

@@ -19,6 +19,13 @@ See the releases' descriptions on
 [the library's release page](http://github.com/nRF24/RF24/releases) for a list of
 changes.
 
+> [!IMPORTANT]
+> There's going to be major changes in v2.0.
+> As of v1.5, there is [newer API](migration.md) that should be preferred over
+> the @ref deprecated "deprecated API".
+>
+> See our [migration guide](migration.md) to understand what you should update in your code.
+
 ## Useful References
 
 - [RF24 Class Documentation](classRF24.html)

docs/migration.md

@@ -0,0 +1,208 @@
+# Migration guide
+
+@tableofcontents
+
+This is a collection of snippets that highlight preferred API over the deprecated original API.
+
+## isAckPayloadAvailable()
+
+> **Deprecated since v1.4.2**
+
+This function is equivalent to `RF24::available()`.
+Any use of `RF24::isAckPayloadAvailable()` is interchangeable with `RF24::available()`.
+
+<table><tr>
+<th>Old</th>
+<th>New (supported)</th>
+</tr><tr><td>
+
+```cpp
+if radio.isAckPayloadAvailable() { /* .. */ }
+```
+
+</td><td>
+
+```cpp
+if radio.available() { /* .. */ }
+```
+
+</td></tr></table>
+
+## openReadingPipe(uint8_t, uint64_t) and openWritingPipe(uint64_t)
+
+> **Deprecated since v1.3.11**
+
+These function's address parameter used a 64-bit unsigned integer (`uint64_t`).
+The nRF24L01 can only use up to 40 bit addresses.
+Thus, there was unused 24 bits being allocated for addresses using this function.
+
+There are overloaded functions that use a buffer instead:
+
+- `RF24::openReadingPipe(uint8_t, const uint8_t*)`
+- `RF24::openWritingPipe(const uint8_t*)`
+
+These eliminates the extra 24 bits by only using the length of the buffer (`uint8_t*`)
+specified by `RF24::setAddressWidth()`.
+
+> [!CAUTION]
+> The endianness (byte order) of a buffer is reversed compared to a 64-bit integer.
+> ```c
+> uint64_t address = 0xB3B4B5B6C2;
+> // is the same address as
+> uint8_t address[5] = {0xC2, 0xB6, 0xB5, 0xB4, 0xB3};
+> ```
+> Notice the MSB (Most Significant Byte) `0xC2` is last in the integer but first in the buffer.
+
+<table><tr>
+<th>Old</th>
+<th>New (supported)</th>
+</tr><tr><td>
+
+```cpp
+uint64_t address = 0xB3B4B5B6C2;
+radio.openReadingPipe(1, address);
+```
+
+</td><td>
+
+```cpp
+uint8_t address[5] = {0xC2, 0xB6, 0xB5, 0xB4, 0xB3};
+radio.openReadingPipe(1, address);
+```
+
+</td></tr></table>
+
+> [!NOTE]
+> Our examples actually use a C-string casted as `uint8_t` array of 6 bytes.
+> That's because a C-string (`char*`) must be NULL terminated (`\0` at the end) in memory.
+> ```c
+> uint8_t address[][6] = { "1Node", "2Node" };
+> // is equivalent to
+> uint8_t address[][6] = { { '1', 'N', 'o', 'd', 'e', '\0' },
+>                          { '2', 'N', 'o', 'd', 'e', '\0' } };
+> ```
+
+## isFifo(bool, bool)
+
+> **Deprecated since v1.4.11**
+
+Introduced as a compliment to `RF24::isFifo(bool)` in v1.4.3, this function was
+supposed to provide specific detail about a specified radio's FIFO. However, it was
+discovered that the function may not highlight binary corruption (`RF24_FIFO_INVALID`)
+observed in the SPI bus' MISO line.
+
+A fix was introduced using enumerated values of `rf24_fifo_state_e`.
+Since then, `RF24::isFifo(bool)` is now preferred as it accurately describes the result.
+
+<table><tr>
+<th>Old</th>
+<th>New (supported)</th>
+</tr><tr><td>
+
+```cpp
+bool rxFifoEmpty = radio.isFifo(false, true);
+```
+
+</td><td>
+
+```cpp
+bool rxFifoEmpty = radio.isFifo(false) == RF24_FIFO_EMPTY;
+```
+
+</td></tr></table>
+
+## maskIRQ()
+
+> **Deprecated since v1.5**
+
+Originally `RF24::maskIRQ()` was the only function provided to influence the radio's IRQ pin.
+However, the 3 required boolean parameters made this prone to bugs in user code.
+The parameters' meaning was confusingly reversed and it was too easy put them in the wrong order.
+
+A better approach was introduced with `RF24::setStatusFlags()`.
+It's 1 parameter accepts values defined by the `rf24_irq_flags_e` enumerated constants.
+
+<table><tr>
+<th>Old</th>
+<th>New (supported)</th>
+</tr><tr><td>
+
+```cpp
+// IRQ pin only activated by "RX Data Ready" event
+radio.maskIRQ(1, 1, 0);
+
+// IRQ pin activated by "TX Data Sent" and TX Data Failed" events
+radio.maskIRQ(0, 0, 1);
+
+// IRQ pin activated by all events
+radio.maskIRQ(0, 0, 0);
+
+// IRQ pin disabled
+radio.maskIRQ(1, 1, 1);
+```
+
+</td><td>
+
+```cpp
+// IRQ pin only activated by "RX Data Ready" event
+radio.setStatusFlags(RF24_RX_DR);
+
+// IRQ pin activated by "TX Data Sent" and TX Data Failed" events
+radio.setStatusFlags(RF24_TX_DS | RF24_TX_DF);
+
+// IRQ pin activated by all events
+radio.setStatusFlags(RF24_IRQ_ALL);
+
+// IRQ pin disabled
+radio.setStatusFlags(RF24_IRQ_NONE);
+// or equivalently
+radio.setStatusFlags();
+```
+
+</td></tr></table>
+
+
+## whatHappened()
+
+> **Deprecated since v1.5**
+
+Originally, `RF24::whatHappened()` was the only way to clear the events that triggered the IRQ pin.
+Like `maskIRQ()`, this was also prone to bugs because of the 3 required boolean parameters
+(passed by reference).
+
+The aptly named `RF24::clearStatusFlags()` is designed to be a replacement for `RF24::whatHappened()`.
+Like `RF24::clearStatusFlags()`, `RF24::setStatusFlags()` takes 1 parameter whose value is defined by
+the `rf24_irq_flags_e` enumerated constants.
+Additionally, it returns the STATUS byte containing the flags that caused the IRQ pin to go active LOW.
+This allows the user code to allocate less memory when diagnosing the IRQ pin's meaning.
+
+<table><tr>
+<th>Old</th>
+<th>New (supported)</th>
+</tr><tr><td>
+
+```cpp
+bool tx_ds, tx_df, rx_dr;
+radio.whatHappened(tx_ds, tx_df, rx_dr);
+```
+
+</td><td>
+
+```cpp
+uint8_t flags = radio.clearStatusFlags();
+// or equivalently
+uint8_t flags = radio.clearStatusFlags(RF24_IRQ_ALL);
+
+// focus on the events you care about
+if (flags & RF24_TX_DS) { /* TX data sent */ }
+if (flags & RF24_TX_DF) { /* TX data failed to send */ }
+if (flags & RF24_RX_DR) { /* RX data is in the RX FIFO */ }
+
+// only clear the "TX Data Sent" and TX Data Failed" events
+radio.clearStatusFlags(RF24_TX_DS | RF24_TX_DF);
+
+// only clear the "RX Data Ready" event
+radio.clearStatusFlags(RF24_RX_DR);
+```
+
+</td></tr></table>