mimxrt/machine_rtc: Deprecate RTC.cancel in MicroPython v2.

The current documentation for the `machine.RTC` class contains information
about the `RTC.cancel` method for cancelling pending alarms.

However only two ports (cc3200 and mimxrt) implement this functionality
but under a different name: `RTC.alarm_cancel`.  The mimxrt port also
implements `RTC.cancel` but it is aliased to `RTC.alarm_cancel` anyway.

To maintain naming consistency, this commit updates the documentation to
officially define `RTC.alarm_cancel` as the method to call to cancel
pending alarms and deprecates mimxrt's `RTC.cancel` implementation.
`RTC.cancel` in the mimxrt port is thus scheduled for removal in
MicroPython v2.

Signed-off-by: Alessandro Gatti <[email protected]>

Author: agatti

docs/library/machine.RTC.rst

@@ -62,10 +62,13 @@ Methods
 
    Get the number of milliseconds left before the alarm expires.
 
-.. method:: RTC.cancel(alarm_id=0)
+.. method:: RTC.alarm_cancel(alarm_id=0)
 
    Cancel a running alarm.
 
+   The mimxrt port also exposes this function as ``RTC.cancel(alarm_id=0)``, but this is
+   scheduled to be removed in MicroPython 2.0.
+
 .. method:: RTC.irq(*, trigger, handler=None, wake=machine.IDLE)
 
    Create an irq object triggered by a real time clock alarm.

ports/mimxrt/machine_rtc.c

@@ -394,7 +394,9 @@ static const mp_rom_map_elem_t machine_rtc_locals_dict_table[] = {
     { MP_ROM_QSTR(MP_QSTR_alarm), MP_ROM_PTR(&machine_rtc_alarm_obj) },
     { MP_ROM_QSTR(MP_QSTR_alarm_left), MP_ROM_PTR(&machine_rtc_alarm_left_obj) },
     { MP_ROM_QSTR(MP_QSTR_alarm_cancel), MP_ROM_PTR(&machine_rtc_alarm_cancel_obj) },
+    #if !MICROPY_PREVIEW_VERSION_2
     { MP_ROM_QSTR(MP_QSTR_cancel), MP_ROM_PTR(&machine_rtc_alarm_cancel_obj) },
+    #endif
     { MP_ROM_QSTR(MP_QSTR_irq), MP_ROM_PTR(&machine_rtc_irq_obj) },
     { MP_ROM_QSTR(MP_QSTR_ALARM0), MP_ROM_INT(0) },
 };