From 68d36ee93ecdd67d240d1ac2db879c84b18f83a6 Mon Sep 17 00:00:00 2001
From: ainyan03 <205502311+ainyan03@users.noreply.github.com>
Date: Fri, 30 Oct 2026 09:14:50 +0000
Subject: [PATCH] Clarify alarm overloads and charge setter results

Attach alarm documentation to the callable overload and explain that failed charge requests may still have changed hardware settings.
---
 src/utility/Power_Class.hpp | 13 +++++++++----
 src/utility/RTC_Class.hpp   | 15 +++++++++------
 2 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/src/utility/Power_Class.hpp b/src/utility/Power_Class.hpp
index 8d8a364..c1db0f1 100644
--- a/src/utility/Power_Class.hpp
+++ b/src/utility/Power_Class.hpp
@@ -364,15 +364,18 @@ namespace m5
 
     /// set battery charge enable.
     /// @param enable true=enable / false=disable
-    /// @return true if the path exists and the write succeeded.
-    /// @note false only means that the requested setting did not take effect;
-    /// it says nothing about what the hardware currently holds.
+    /// @return true if the path exists and every required write and cleanup step succeeded.
+    /// @note false means the request could not be confirmed: the path is missing,
+    /// a communication failed, or a step after the write failed. The setting may
+    /// or may not have been applied.
     bool setBatteryCharge(bool enable);
 
     /// set battery charge current
     /// @param max_mA milli ampere.
     /// @param applied_mA optional. receives the step that was applied.
-    /// @return true if the path exists and the write succeeded.
+    /// @return true if the path exists and every required configuration step succeeded.
+    /// @note false means the request could not be confirmed. The path may be missing
+    /// or a communication may have failed; the setting may or may not have been applied.
     /// @note The highest step not exceeding max_mA is selected; a request below
     /// the lowest step is clamped up to it instead of being rejected. 0 is not a
     /// step: use setBatteryCharge(false) to stop charging.
@@ -392,6 +395,8 @@ namespace m5
     /// @param max_mV milli volt.
     /// @param applied_mV optional. receives the step that was applied.
     /// @return true if the path exists and the write succeeded.
+    /// @note false means the request could not be confirmed. The path may be missing
+    /// or a communication may have failed; the setting may or may not have been applied.
     /// @note The step selection rule is the same as setChargeCurrent.
     /// @note applied_mV is left untouched when false is returned.
     /// @note IP5306 steps and applied_mV are nominal values. The chip charges
diff --git a/src/utility/RTC_Class.hpp b/src/utility/RTC_Class.hpp
index 8705579..edc9e7f 100644
--- a/src/utility/RTC_Class.hpp
+++ b/src/utility/RTC_Class.hpp
@@ -68,6 +68,13 @@ namespace m5
     /// Whether the RTC can represent this alarm request; nothing is written.
     bool canSetAlarm(const rtc_date_t* date, const rtc_time_t* time) const { return _rtc_instance ? _rtc_instance->canSetAlarm(date, time) : false; }
 
+    /// Removed. setAlarmIRQ(seconds) programmed the periodic timer, not the alarm;
+    /// use setTimerIRQ(seconds * 1000). Deleted (instead of just removed) so that
+    /// setAlarmIRQ(0) fails to compile rather than silently binding to the tm* overload.
+    bool setAlarmIRQ(int afterSeconds) = delete;
+
+    /// Same as setAlarmIRQ(const rtc_date_t*, const rtc_time_t*).
+    bool setAlarmIRQ(const tm* datetime);
     /// Set (or clear) the alarm.
     /// The alarm uses minutes, hours, date and weekDay; a field set to -1 is a wildcard.
     /// seconds, month and year are ignored (one-minute resolution). A request with no
@@ -85,14 +92,10 @@ namespace m5
     /// @note See setTimerIRQ() for the M5PM1 relay note.
     /// @note PowerHub: each alarm register write is followed by a 50 ms pause so the STM32
     ///       front-end can apply it; a set or clear takes about 100-200 ms.
-    /// Removed. setAlarmIRQ(seconds) programmed the periodic timer, not the alarm;
-    /// use setTimerIRQ(seconds * 1000). Deleted (instead of just removed) so that
-    /// setAlarmIRQ(0) fails to compile rather than silently binding to the tm* overload.
-    bool setAlarmIRQ(int afterSeconds) = delete;
-
-    bool setAlarmIRQ(const tm* datetime);
     bool setAlarmIRQ(const rtc_date_t* date, const rtc_time_t* time);
+    /// Same as setAlarmIRQ(const rtc_date_t*, const rtc_time_t*).
     bool setAlarmIRQ(const rtc_date_t &date, const rtc_time_t &time) { return setAlarmIRQ(&date, &time); }
+    /// Same as setAlarmIRQ(const rtc_date_t*, const rtc_time_t*).
     bool setAlarmIRQ(const rtc_time_t &time) { return setAlarmIRQ(nullptr, &time); }
 
     void setSystemTimeFromRtc(struct timezone* tz = nullptr);