From 11ac393075637caf3455708a82ee8ebbca675486 Mon Sep 17 00:00:00 2001
From: Scott <scott@wannabe.house>
Date: Wed, 12 Jan 2022 20:56:31 -0800
Subject: [PATCH] Update comments.

---
 state_tracker.py | 31 ++++++++++++++++++++++++++++---
 1 file changed, 28 insertions(+), 3 deletions(-)

diff --git a/state_tracker.py b/state_tracker.py
index 4f77ff4..9ce61e3 100644
--- a/state_tracker.py
+++ b/state_tracker.py
@@ -20,8 +20,8 @@ class StateTracker(ABC):
     invoked via the heartbeat() method.  This method, in turn, invokes
     update() with update_ids according to a schedule / periodicity
     provided to the c'tor.
-    """
 
+    """
     def __init__(self, update_ids_to_update_secs: Dict[str, float]) -> None:
         """The update_ids_to_update_secs dict parameter describes one or more
         update types (unique update_ids) and the periodicity(ies), in
@@ -30,6 +30,7 @@ class StateTracker(ABC):
         Note that, when more than one update is overdue, they will be
         invoked in order by their update_ids so care in choosing these
         identifiers may be in order.
+
         """
         self.update_ids_to_update_secs = update_ids_to_update_secs
         self.last_reminder_ts: Dict[str, Optional[datetime.datetime]] = {}
@@ -49,6 +50,7 @@ class StateTracker(ABC):
         The now param is the approximate current timestamp and the
         last_invocation param is the last time you were invoked (or
         None on the first invocation)
+
         """
         pass
 
@@ -64,6 +66,7 @@ class StateTracker(ABC):
         Setting force_all_updates_to_run will invoke all updates
         (ordered by update_id) immediately ignoring whether or not
         they are due.
+
         """
         self.now = datetime.datetime.now(tz=pytz.timezone("US/Pacific"))
         for update_id in sorted(self.last_reminder_ts.keys()):
@@ -101,13 +104,15 @@ class AutomaticStateTracker(StateTracker):
     """Just like HeartbeatCurrentState but you don't need to pump the
     heartbeat; it runs on a background thread.  Call .shutdown() to
     terminate the updates.
-    """
 
+    """
     @background_thread
     def pace_maker(self, should_terminate) -> None:
         """Entry point for a background thread to own calling heartbeat()
         at regular intervals so that the main thread doesn't need to do
-        so."""
+        so.
+
+        """
         while True:
             if should_terminate.is_set():
                 logger.debug('pace_maker noticed event; shutting down')
@@ -138,6 +143,7 @@ class AutomaticStateTracker(StateTracker):
     def shutdown(self):
         """Terminates the background thread and waits for it to tear down.
         This may block for as long as self.sleep_delay.
+
         """
         logger.debug(
             'Setting shutdown event and waiting for background thread.'
@@ -148,7 +154,26 @@ class AutomaticStateTracker(StateTracker):
 
 
 class WaitableAutomaticStateTracker(AutomaticStateTracker):
+    """This is an AutomaticStateTracker that exposes a wait method which
+    will block the calling thread until the state changes with an
+    optional timeout.  The caller should check the return value of
+    wait; it will be true if something changed and false if the wait
+    simply timed out.  If the return value is true, the instance
+    should be reset() before wait is called again.
 
+    Example usage:
+
+        detector = waitable_presence.WaitableAutomaticStateSubclass()
+        while True:
+            changed = detector.wait(timeout=60 * 5)
+            if changed:
+                detector.reset()
+                # Figure out what changed and react
+            else:
+                # Just a timeout; no need to reset.  Maybe do something
+                # else before looping up into wait again.
+
+    """
     def __init__(
             self,
             update_ids_to_update_secs: Dict[str, float],
-- 
2.47.1