From fe2dd53dd6ce9206fa310201b4162f0b4b880314 Mon Sep 17 00:00:00 2001
From: Bryan Weber <bryan.w.weber@gmail.com>
Date: Wed, 25 May 2022 04:55:49 -0400
Subject: [PATCH] [Doc] Add docstrings and versionadded for Units

---
 interfaces/cython/cantera/units.pyx | 38 ++++++++++++++++++++---------
 1 file changed, 27 insertions(+), 11 deletions(-)

diff --git a/interfaces/cython/cantera/units.pyx b/interfaces/cython/cantera/units.pyx
index bf9a013b3e1..b0f399319fc 100644
--- a/interfaces/cython/cantera/units.pyx
+++ b/interfaces/cython/cantera/units.pyx
@@ -1,6 +1,7 @@
 from __future__ import annotations
 # This file is part of Cantera. See License.txt in the top-level directory or
 # at https://cantera.org/license.txt for license and copyright information.
+from __future__ import annotations
 
 cdef class Units:
     """
@@ -19,23 +20,38 @@ cdef class Units:
         if name:
             self.units = CxxUnits(stringify(name), True)
 
-    def __repr__(self):
-        return f"<Units({pystr(self.units.str())}) at {id(self):0x}>"
+    def __repr__(self) -> str:
+        return f"<Units({str(self)}) at {id(self):0x}>"
 
-    def __str__(self):
+    def __str__(self) -> str:
         return pystr(self.units.str())
 
-    def dimension(self, primary):
+    def dimension(self, primary: str) -> float:
+        """The dimension of the given unit component.
+
+        .. versionadded:: 3.0
+
+        :param: primary, a string with the desired unit component. One of ``"mass"``,
+        ``"length"``, ``"time"``, ``"temperature"``, ``"current"``, or ``"quantity"``.
+        """
         return self.units.dimension(stringify(primary))
 
-    property dimensions:
-        def __get__(self):
-            dimensions = ("mass", "length", "time", "temperature", "current", "quantity")
-            return {d: self.units.dimension(stringify(d)) for d in dimensions}
+    @property
+    def dimensions(self) -> dict[str, str]:
+        """A dictionary of the primary unit components to their dimensions.
 
-    property factor:
-        def __get__(self):
-            return self.units.factor()
+        .. versionadded:: 3.0
+        """
+        dimensions = ("mass", "length", "time", "temperature", "current", "quantity")
+        return {d: self.dimension(d) for d in dimensions}
+
+    @property
+    def factor(self) -> float:
+        """The factor required to convert from this unit to Cantera's base units.
+
+        .. versionadded:: 3.0
+        """
+        return self.units.factor()
 
     @staticmethod
     cdef copy(CxxUnits other):