From 45eeade52f573eafa55b6b29927d661bf5ec51d2 Mon Sep 17 00:00:00 2001
From: Chan-Ho Suh <chanhosuh@gmail.com>
Date: Mon, 25 Sep 2023 16:42:11 -0400
Subject: [PATCH] Expand docstrings

---
 curvesim/utils/datetime.py | 39 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 37 insertions(+), 2 deletions(-)

diff --git a/curvesim/utils/datetime.py b/curvesim/utils/datetime.py
index 860742bdc..08813947d 100644
--- a/curvesim/utils/datetime.py
+++ b/curvesim/utils/datetime.py
@@ -1,10 +1,34 @@
+"""
+Utility functions for working with datetimes in UTC format.
+
+This module provides custom versions of common datetime operations to ensure
+returned datetimes are always in the UTC timezone and are not naive.
+
+The main goal is to prevent potential issues related to timezone-aware and
+timezone-naive datetime objects.
+
+Recommended style for importing is:
+
+    from curvesim.utils import datetime
+
+    datetime.now()
+
+This syntactically substitutes the `datetime.datetime` class methods with
+this module's functions.
+"""
 from datetime import datetime, timezone
 
 
-def now():
+def now() -> datetime:
     """
     Customized version of `datetime.datetime.now` to ensure
     UTC timezone and format.
+
+    Returns
+    -------
+    datetime
+        Current UTC datetime with hour, minute, second, and microsecond set to 0.
+        This datetime is timezone-aware and is not naive.
     """
     utc_dt = datetime.now(timezone.utc).replace(
         hour=0, minute=0, second=0, microsecond=0
@@ -12,10 +36,21 @@ def now():
     return utc_dt
 
 
-def fromtimestamp(timestamp):
+def fromtimestamp(timestamp: int) -> datetime:
     """
     Customized version of `datetime.datetime.fromtimestamp` to ensure
     UTC timezone and format.
+
+    Parameters
+    ----------
+    timestamp : int
+        Unix timestamp to be converted to datetime.
+
+    Returns
+    -------
+    datetime
+        The UTC datetime representation of the given timestamp.
+        This datetime is timezone-aware and is not naive.
     """
     utc_timestamp = datetime.fromtimestamp(timestamp, tz=timezone.utc)
     return utc_timestamp