[radio] clarify otPlatRadioReceiveAt() behavior (openthread#11221)

This commit clarifies the documentation for `otPlatRadioReceiveAt()`
regarding its behavior when called multiple times after successfully
scheduling a reception window.  If a subsequent call occurs before
the start of the previous window, it MUST cancel the previous window
and effectively replace it. If the call occurs after the start of
the previously scheduled window, even if still within it, it MUST
NOT impact the ongoing reception.

include/openthread/instance.h

@@ -52,7 +52,7 @@ extern "C" {
  *
  * @note This number versions both OpenThread platform and user APIs.
  */
-#define OPENTHREAD_API_VERSION (476)
+#define OPENTHREAD_API_VERSION (477)
 
 /**
  * @addtogroup api-instance

include/openthread/platform/radio.h

@@ -865,6 +865,17 @@ otError otPlatRadioReceive(otInstance *aInstance, uint8_t aChannel);
 /**
  * Schedule a radio reception window at a specific time and duration.
  *
+ * After a radio reception is successfully scheduled for a future time and duration, a subsequent call to this
+ * function MUST be handled as follows:
+ *
+ * - If the start time of the previously scheduled reception window has not yet been reached, the new call to
+ *   `otPlatRadioReceiveAt()` MUST cancel the previous schedule, effectively replacing it.
+ *
+ * - If the start of the previous window has already passed, the previous receive schedule is already being executed
+ *   by the radio and MUST NOT be replaced or impacted. The new call to `otPlatRadioReceiveAt()` would then schedule
+ *   a new future receive window. In particular, if the new `otPlatRadioReceiveAt()` call occurs after the start
+ *   but while still within the previous reception window, the ongoing reception window MUST NOT be impacted.
+ *
  * @param[in]  aChannel   The radio channel on which to receive.
  * @param[in]  aStart     The receive window start time relative to the local
  *                        radio clock, see `otPlatRadioGetNow`. The radio
@@ -879,7 +890,7 @@ otError otPlatRadioReceive(otInstance *aInstance, uint8_t aChannel);
  *                        reception has either succeeded or failed.
  *
  * @retval OT_ERROR_NONE    Successfully scheduled receive window.
- * @retval OT_ERROR_FAILED  The receive window could not be scheduled.
+ * @retval OT_ERROR_FAILED  The receive window could not be scheduled. For example, if @p aStart is in the past.
  */
 otError otPlatRadioReceiveAt(otInstance *aInstance, uint8_t aChannel, uint32_t aStart, uint32_t aDuration);