Update rtc_set_datetime docs to point out that the written value may …

…not be immediately visible (raspberrypi#832)

src/rp2_common/hardware_rtc/include/hardware/rtc.h

@@ -47,6 +47,10 @@ void rtc_init(void);
 /*! \brief Set the RTC to the specified time
  *  \ingroup hardware_rtc
  *
+ * \note Note that after setting the RTC date and time, a subsequent read of the values (e.g. via rtc_get_datetime()) may not
+ * reflect the new setting until up to three cycles of the potentially-much-slower RTC clock domain have passed. This represents a period
+ * of 64 microseconds with the default RTC clock configuration.
+ *
  * \param t Pointer to a \ref datetime_t structure contains time to set
  * \return true if set, false if the passed in datetime was invalid.
  */