From ee759011b3ed16539d421671608f4232e2d6fb1b Mon Sep 17 00:00:00 2001
From: George Rawlinson <george@rawlinson.net.nz>
Date: Fri, 20 Nov 2020 07:50:15 +1300
Subject: [PATCH] docs: add more documentation to classes

---
 src/smbmc/client.py |  8 ++++--
 src/smbmc/models.py | 69 +++++++++++++++++++++++++++++++++++----------
 2 files changed, 59 insertions(+), 18 deletions(-)

diff --git a/src/smbmc/client.py b/src/smbmc/client.py
index 43087a6..f80a302 100644
--- a/src/smbmc/client.py
+++ b/src/smbmc/client.py
@@ -24,6 +24,7 @@ class Client:
             username: Username.
             password: Password.
             session_timeout: Session timeout of the BMC (in minutes).
+                default: 30 minutes.
         """
         self.server = server
         self.username = username
@@ -84,7 +85,8 @@ class Client:
         """Acquire metrics for all power supplies.
 
         Returns:
-            str: XML response.
+            list[PowerSupply]: All power supplies available on the PMBus
+            interface.
         """
         r = self._query(
             data={
@@ -101,7 +103,7 @@ class Client:
         """Acquire metrics for all sensors.
 
         Returns:
-            str: XML response.
+            list[Sensor]: A list of all sensors available to the BMC.
         """
         r = self._query(
             data={
@@ -115,7 +117,7 @@ class Client:
         return sensors
 
     def get_metrics(self, metrics=["pmbus", "sensor"]):  # noqa: C901
-        """Fetch metrics with minimum network calls.
+        """Fetch all metrics available.
 
         Args:
             metrics: List of metric(s) to query.
diff --git a/src/smbmc/models.py b/src/smbmc/models.py
index 25f2360..0a38f72 100644
--- a/src/smbmc/models.py
+++ b/src/smbmc/models.py
@@ -4,7 +4,14 @@ from enum import IntFlag
 
 
 class SensorStateEnum(IntEnum):
-    """Enumeration of sensor states."""
+    """Enumeration of sensor states.
+
+    Possible Values:
+
+    - Unspecified
+    - Present
+    - Not Present
+    """
 
     UNSPECIFIED = 0
     PRESENT = 1
@@ -12,7 +19,17 @@ class SensorStateEnum(IntEnum):
 
 
 class SensorUnitEnum(IntEnum):
-    """Enumeration of sensor units."""
+    """Enumeration of sensor units.
+
+    Possible Values:
+
+    - Unspecified
+    - degrees Celsius (°C)
+    - Volts (V)
+    - Amps (A)
+    - Watts (W)
+    - revolutions per minute (rpm)
+    """
 
     UNSPECIFIED = 0
     DEGREES_CELSIUS = 1
@@ -23,7 +40,16 @@ class SensorUnitEnum(IntEnum):
 
 
 class SensorTypeEnum(IntEnum):
-    """Enumeration of sensor types."""
+    """Enumeration of sensor types.
+
+    Possible Values:
+
+    - Unspecified
+    - Temperature
+    - Voltage
+    - Fan
+    - Power Supply
+    """
 
     UNSPECIFIED = 0
     TEMPERATURE = 1
@@ -33,7 +59,20 @@ class SensorTypeEnum(IntEnum):
 
 
 class PowerSupplyFlag(IntFlag):
-    """Flags for power supply specific events."""
+    """Bitflag for power supply specific events.
+
+    Flags:
+
+    - Unspecified
+    - Presence Detected
+    - Failure
+    - Predictive Failure
+    - Source Input Lost
+    - Source Input Out of Range
+    - Source Input Detected (Out of Range)
+    - Configuration Error
+    - Standby
+    """
 
     UNSPECIFIED = 0
     PRESENCE_DETECTED = 1
@@ -53,16 +92,16 @@ class Sensor:
         id: Psuedo-unique id.
         name: Sensor name.
         type: Sensor type.
-        unit: Reading unit. e.g. Temperature - degrees Celsius.
+        unit: Reading unit.
         state: Sensor state.
         flags: Discrete sensors only; type specific flags.
         reading: Sensor reading.
-        lnr: Lower non-recoverable indicator.
-        lc: Lower critical indicator.
-        lnc: Lower non-critical indicator.
-        unc: Upper non-critical indicator.
-        uc: Upper critical indicator.
-        unr: Upper non-recoverable indicator.
+        lnr: Lower non-recoverable threshold.
+        lc: Lower critical threshold.
+        lnc: Lower non-critical threshold.
+        unc: Upper non-critical threshold.
+        uc: Upper critical threshold.
+        unr: Upper non-recoverable threshold.
     """
 
     def __init__(self):
@@ -97,10 +136,10 @@ class PowerSupply:
         output_voltage: Output voltage (V_DC).
         output_current: Output current (A).
         output_power: Output power (W).
-        temp_1: Temperature 1. Possibly intake (degrees Celsius).
-        temp_2: Temperature 2. Possibly outlet (degrees Celsius).
-        fan_1: Fan 1. Possibly intake (r.p.m.).
-        fan_2: Fan 2. Possibly outlet (r.p.m.).
+        temp_1: Temperature 1. Possibly intake (°C).
+        temp_2: Temperature 2. Possibly outlet (°C).
+        fan_1: Fan 1. Possibly intake (rpm).
+        fan_2: Fan 2. Possibly outlet (rpm).
     """
 
     def __init__(self):