From c762de29c6491790908451aa20f6aa12fdfa9722 Mon Sep 17 00:00:00 2001
From: Kelly Brazil <kellyjonbrazil@gmail.com>
Date: Wed, 24 Mar 2021 12:47:57 -0700
Subject: [PATCH] doc updates

---
 docs/utils.md | 30 ++++++++++++++++++++++++++++++
 jc/utils.py   |  4 ++--
 2 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/docs/utils.md b/docs/utils.md
index 8fe5f7a9..2ea95347 100644
--- a/docs/utils.md
+++ b/docs/utils.md
@@ -68,3 +68,33 @@ Returns:
 
     Boolean      True if input string (data) contains non-whitespace characters, otherwise False
 
+
+## parse_datetime_to_timestamp
+```python
+parse_datetime_to_timestamp(data)
+```
+
+Input a date-time text string of several formats and convert to a naive or timezone-aware epoch timestamp in UTC
+
+Parameters:
+
+    data:        (string) a string representation of a date-time in several supported formats
+
+Returns:
+
+    Dict/None    A Dictionary of the following format:
+
+                 {
+                     "format":               integer,     # for debugging purposes
+                     "timestamp_naive":      integer,     # timestamp based on locally configured timezone
+                     "timestamp_utc":        integer      # aware timestamp only if UTC timezone detected
+                 }
+
+                 The format integer denotes which date_time format conversion succeeded.
+                 The timestamp_naive integer is the converted date-time string to a naive epoch timestamp.
+                 The timestamp_utc integer is the converted date-time string to an aware epoch timestamp
+                     in the UTC timezone. If an aware conversion cannot be performed (e.g. the UTC timezone
+                     is not found in the date-time string), then this field will be None.
+
+                 If the conversion completely fails, None is returned instead of a Dictionary
+
diff --git a/jc/utils.py b/jc/utils.py
index 69301eb9..5def9303 100644
--- a/jc/utils.py
+++ b/jc/utils.py
@@ -100,8 +100,8 @@ def parse_datetime_to_timestamp(data):
         Dict/None    A Dictionary of the following format:
 
                      {
-                         "format":               integer,
-                         "timestamp_naive":      integer,
+                         "format":               integer,     # for debugging purposes
+                         "timestamp_naive":      integer,     # timestamp based on locally configured timezone
                          "timestamp_utc":        integer      # aware timestamp only if UTC timezone detected
                      }