From d7067af522bd05676993290ddcfa06bc9c597984 Mon Sep 17 00:00:00 2001
From: 2Shirt <2xShirt@gmail.com>
Date: Sat, 7 Oct 2023 16:36:17 -0700
Subject: [PATCH] Add data structure description to Sensors() object

---
 scripts/wk/hw/sensors.py | 37 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 36 insertions(+), 1 deletion(-)

diff --git a/scripts/wk/hw/sensors.py b/scripts/wk/hw/sensors.py
index 00d5d33f..2ddb9163 100644
--- a/scripts/wk/hw/sensors.py
+++ b/scripts/wk/hw/sensors.py
@@ -37,7 +37,42 @@ class ThermalLimitReachedError(RuntimeError):
 
 # Classes
 class Sensors():
-  """Class for holding sensor specific data."""
+  """Class for holding sensor specific data.
+
+  # Sensor data structure
+  #
+  # Section       # CPUTemps / Other
+  #   Adapters    # coretemp / acpi / nvme / etc
+  #     Sources   # Core 1 / SODIMM / Sensor X / etc
+  #       Label   # temp1_input / etc (i.e. lm_sensor label)
+  #       Max     # 99.0
+  #       X       # 55.0 (where X is Idle/Current/Sysbench/etc)
+  #       Temps   # [39.0, 38.0, 40.0, 39.0, 38.0, ...]
+  #
+  # e.g.
+  #   { 'CPUTemps': { 'coretemp-isa-0000': { 'Core 0': { 'Average': 44.5,
+  #                                                      'Current': 44.0,
+  #                                                      'Idle': 44.5,
+  #                                                      'Label': 'temp2_input',
+  #                                                      'Max': 45.0,
+  #                                                      'Temps': [ 45.0,
+  #                                                                 45.0,
+  #                                                                 ...,
+  #                                                                 42.0]}}}}
+  #
+  # Sensor history data structure
+  # [ ('Name of "run"', sensor_data_structure_described_above), ]
+  #
+  # e.g.
+  # [
+  #   ( 'Idle',
+  #     { 'CPUTemps': { 'coretemp-isa-0000': { 'Core 0': { 'Max': 45.0, ..., }}}}
+  #   ),
+  #   ( 'Sysbench',
+  #     { 'CPUTemps': { 'coretemp-isa-0000': { 'Core 0': { 'Max': 85.0, ..., }}}}
+  #   ),
+  # ]
+  """
   def __init__(self):
     self.background_thread: Thread | None = None
     self.data: dict[Any, Any] = get_sensor_data()