doc updates

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
+

jc/utils.py

@@ -100,8 +100,8 @@ def parse_datetime_to_timestamp(data):
         Dict/None    A Dictionary of the following format:
 
                      {
-                         "format":               integer,
+                         "format":               integer,     # for debugging purposes
-                         "timestamp_naive":      integer,
+                         "timestamp_naive":      integer,     # timestamp based on locally configured timezone
                          "timestamp_utc":        integer      # aware timestamp only if UTC timezone detected
                      }