More doc updates.

[python_utils.git] / state_tracker.py

diff --git a/state_tracker.py b/state_tracker.py
index 3e2060f4f656cece29dd73cbe7b58d93691741a6..0476d1a65a7eeebac6f5d4ab8ee89af6467be029 100644 (file)
--- a/state_tracker.py
+++ b/state_tracker.py
@@ -3,9 +3,9 @@
 # © Copyright 2021-2022, Scott Gasch
 
 """Several helpers to keep track of internal state via periodic
 # © Copyright 2021-2022, Scott Gasch
 
 """Several helpers to keep track of internal state via periodic

-polling.  :class:StateTracker expects to be invoked periodically to
-maintain state whereas the others (:class:AutomaticStateTracker and
-:class:WaitableAutomaticStateTracker) automatically update themselves
+polling.  :class:`StateTracker` expects to be invoked periodically to
+maintain state whereas the others (:class:`AutomaticStateTracker` and
+:class:`WaitableAutomaticStateTracker`) automatically update themselves

 and, optionally, expose an event for client code to wait on state
 changes.
 """
 and, optionally, expose an event for client code to wait on state
 changes.
 """


@@ -73,7 +73,7 @@ class StateTracker(ABC):
 
         Args:
             update_id: the string you passed to the c'tor as a key in
 
         Args:
             update_id: the string you passed to the c'tor as a key in

-                the update_ids_to_update_secs dict.  :meth:update will
+                the update_ids_to_update_secs dict.  :meth:`update` will

                 only be invoked on the shoulder, at most, every update_secs
                 seconds.
 
                 only be invoked on the shoulder, at most, every update_secs
                 seconds.
 


@@ -87,7 +87,7 @@ class StateTracker(ABC):
     def heartbeat(self, *, force_all_updates_to_run: bool = False) -> None:
         """Invoke this method to cause the StateTracker instance to identify
         and invoke any overdue updates based on the schedule passed to
     def heartbeat(self, *, force_all_updates_to_run: bool = False) -> None:
         """Invoke this method to cause the StateTracker instance to identify
         and invoke any overdue updates based on the schedule passed to

-        the c'tor.  In the base :class:StateTracker class, this method must
+        the c'tor.  In the base :class:`StateTracker` class, this method must

         be invoked manually by a thread from external code.  Other subclasses
         are available that create their own updater threads (see below).
 
         be invoked manually by a thread from external code.  Other subclasses
         are available that create their own updater threads (see below).
 


@@ -126,15 +126,15 @@ class StateTracker(ABC):
 
 
 class AutomaticStateTracker(StateTracker):
 
 
 class AutomaticStateTracker(StateTracker):

-    """Just like :class:StateTracker but you don't need to pump the
-    :meth:heartbeat method periodically because we create a background
-    thread that manages periodic calling.  You must call :meth:shutdown,
+    """Just like :class:`StateTracker` but you don't need to pump the
+    :meth:`heartbeat` method periodically because we create a background
+    thread that manages periodic calling.  You must call :meth:`shutdown`,

     though, in order to terminate the update thread.
     """
 
     @background_thread
     def pace_maker(self, should_terminate: threading.Event) -> None:
     though, in order to terminate the update thread.
     """
 
     @background_thread
     def pace_maker(self, should_terminate: threading.Event) -> None:

-        """Entry point for a background thread to own calling :meth:heartbeat
+        """Entry point for a background thread to own calling :meth:`heartbeat`

         at regular intervals so that the main thread doesn't need to
         do so.
         """
         at regular intervals so that the main thread doesn't need to
         do so.
         """


@@ -170,7 +170,7 @@ class AutomaticStateTracker(StateTracker):
 
             override_sleep_delay: By default, this class determines
                 how long the background thread should sleep between
 
             override_sleep_delay: By default, this class determines
                 how long the background thread should sleep between

-                automatic invocations to :meth:heartbeat based on the
+                automatic invocations to :meth:`heartbeat` based on the

                 period of each update type in update_ids_to_update_secs.
                 If this argument is non-None, it overrides this computation
                 and uses this period as the sleep in the background thread.
                 period of each update type in update_ids_to_update_secs.
                 If this argument is non-None, it overrides this computation
                 and uses this period as the sleep in the background thread.


@@ -244,7 +244,7 @@ class WaitableAutomaticStateTracker(AutomaticStateTracker):
 
             override_sleep_delay: By default, this class determines
                 how long the background thread should sleep between
 
             override_sleep_delay: By default, this class determines
                 how long the background thread should sleep between

-                automatic invocations to :meth:heartbeat based on the
+                automatic invocations to :meth:`heartbeat` based on the

                 period of each update type in update_ids_to_update_secs.
                 If this argument is non-None, it overrides this computation
                 and uses this period as the sleep in the background thread.
                 period of each update type in update_ids_to_update_secs.
                 If this argument is non-None, it overrides this computation
                 and uses this period as the sleep in the background thread.