From 440abf2b56afdf1149a6e46399cc3dfff564d0c3 Mon Sep 17 00:00:00 2001
From: Lance Edgar <lance@edbob.org>
Date: Sat, 6 Oct 2018 17:39:54 -0500
Subject: [PATCH] Improve docstrings for some model attributes

---
 rattail_tempmon/db/model.py | 37 +++++++++++++++++++++++++++++--------
 1 file changed, 29 insertions(+), 8 deletions(-)

diff --git a/rattail_tempmon/db/model.py b/rattail_tempmon/db/model.py
index 74bb1a8..b64353e 100644
--- a/rattail_tempmon/db/model.py
+++ b/rattail_tempmon/db/model.py
@@ -70,15 +70,25 @@ class Client(Base):
     Any arbitrary notes for the client.
     """)
 
-    enabled = sa.Column(sa.Boolean(), nullable=False, default=False)
-    online = sa.Column(sa.Boolean(), nullable=False, default=False)
+    enabled = sa.Column(sa.Boolean(), nullable=False, default=False, doc="""
+    Whether the client should be considered enabled (active).  If set, the
+    client will be expected to take readings (but only for "enabled" probes)
+    and the server will monitor them to ensure they are within the expected
+    range etc.
+    """)
+
+    online = sa.Column(sa.Boolean(), nullable=False, default=False, doc="""
+    Whether the client is known to be online currently.  When a client takes
+    readings, it will mark itself as online.  If the server notices that the
+    readings have stopped, it will mark the client as *not* online.
+    """)
 
     archived = sa.Column(sa.Boolean(), nullable=False, default=False, doc="""
     Flag indicating this client is "archived".  This typically means that the
-    client itself no longer exists etc. but that the configuration for it
-    should be retained, e.g. to be used as a reference later etc.  Note that
-    "archiving" a client is different from "disabling" it; the latter being
-    more temporary.
+    client itself no longer exists but that the configuration for it should be
+    retained, to be used as a reference later etc.  Note that "archiving" a
+    client is different from "disabling" it; i.e. disabling is temporary and
+    archiving is more for the long term.
     """)
 
     def __str__(self):
@@ -124,8 +134,19 @@ class Probe(Base):
     good_temp_max = sa.Column(sa.Integer(), nullable=False)
     critical_temp_min = sa.Column(sa.Integer(), nullable=False)
     critical_temp_max = sa.Column(sa.Integer(), nullable=False)
-    therm_status_timeout = sa.Column(sa.Integer(), nullable=False)
-    status_alert_timeout = sa.Column(sa.Integer(), nullable=False)
+
+    therm_status_timeout = sa.Column(sa.Integer(), nullable=False, doc="""
+    Number of minutes the temperature is allowed to be "high" before the first
+    "high temp" email alert is sent.  This is typically meant to account for
+    the length of the defrost cycle.  Note that this does *not* affect the
+    "critical temp" emails; those are sent as soon as critical temp is reached.
+    """)
+
+    status_alert_timeout = sa.Column(sa.Integer(), nullable=False, doc="""
+    Number of minutes between successive "high/critical temp" emails.  These
+    alerts will continue to be sent until the temperature returns to normal
+    range.
+    """)
 
     notes = sa.Column(sa.Text(), nullable=True, doc="""
     Any arbitrary notes for the probe.