From baf69b2d890d18707adb05371e9b9a58556139c6 Mon Sep 17 00:00:00 2001
From: Chris Lee <lee.chris.h@gmail.com>
Date: Sun, 3 Nov 2024 20:36:00 -0500
Subject: [PATCH] comments

---
 lib/watering/dose_log.h | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/lib/watering/dose_log.h b/lib/watering/dose_log.h
index 58b52f8..b1e17c6 100644
--- a/lib/watering/dose_log.h
+++ b/lib/watering/dose_log.h
@@ -6,26 +6,38 @@
 
 namespace og3 {
 
-// Track the total number of doses in a day.
+// Track the total number of watering doses in a day.
+// This is done to avoid over-watering in case something goes wrong such as problems
+//  reading the moisture level of the soil.
 class DoseLog {
  public:
   DoseLog(VariableGroup& vg, VariableGroup& cfg_vg);
 
+  // Return the total number of doses in the last 24 hours.
   unsigned dose_count() const { return m_dose_count.value(); }
 
+  // When the pump has run m_max_doses in either a watering cycle or
+  //  a 24 hour period is reached, pause watering for 12 hours.
   bool shouldPauseWatering() const;
 
+  // Call this when a new watering cycle has started.
   void startWatering();
+  // Call this is increment the count of pump doses in the current watering cycle.
   void addDose();
+  // Call this when the current watering cycle has ended.
   void stopWatering();
+  // Call this periodically to time-out watering data which is more that 24 hours old.
   void update();
 
+  // This registers callbacks for Home Assistant MQTT auto-discovery of variables.
   void addHADiscovery(class HADiscovery* had);
 
  private:
-  // Doses in the last 24 hours.
+  // The maximum number of doses to allow in a cycle/day before watering should be paused.
   Variable<unsigned> m_max_doses_per_cycle;
+  // Number of doses in the current watering cycle.
   Variable<unsigned> m_doses_this_cycle;
+  // Number of doses in the last 24 hours.
   Variable<unsigned> m_dose_count;
   bool m_watering = false;