From 115420d3680d5807b0f652aaa149aef40482ab55 Mon Sep 17 00:00:00 2001
From: Kristian Krsnik <git@krsnik.at>
Date: Wed, 4 Oct 2023 17:56:44 +0200
Subject: [PATCH] documentation

---
 outage_detector/main.py | 35 ++++++++++++++++++++++++++++++-----
 1 file changed, 30 insertions(+), 5 deletions(-)

diff --git a/outage_detector/main.py b/outage_detector/main.py
index 6c5c6cb..19243bf 100644
--- a/outage_detector/main.py
+++ b/outage_detector/main.py
@@ -6,7 +6,7 @@ import requests
 
 
 class LogEntry:
-    """Class describing a connection attempt"""
+    '''Class describing a connection attempt.'''
 
     def __init__(self: 'LogEntry', log_entry: str) -> None:
         self.date = datetime.strptime(log_entry[1:20], '%Y-%m-%d %H:%M:%S')
@@ -15,7 +15,13 @@ class LogEntry:
 
 
 def printOutages(filepath: str, time: int) -> None:
-    """Print outages from a log file"""
+    '''
+        Print outages from a log file
+    
+        `filepath` Path to a file with connection logs.
+
+        `time` Minimum duration for a connection loss to be considered an outage.
+    '''
 
     with open(filepath, 'r') as file:
         log = list(map(lambda x: LogEntry(x), file.readlines()))
@@ -60,7 +66,13 @@ def printOutages(filepath: str, time: int) -> None:
 
 
 def isOnline(host: str, timeout: int) -> bool:
-    """Check if connection to a host can be established"""
+    '''
+        Check if connection to a host can be established.
+
+        `host` IP or hostname of a server to query.
+
+        `timeout` Set the timeout in seconds to use for the connection test.
+    '''
 
     try:
         requests.head(f"https://{host}", timeout=timeout)
@@ -70,7 +82,15 @@ def isOnline(host: str, timeout: int) -> bool:
 
 
 def log(host: str, timeout: int, filepath: None | str = None) -> None:
-    """Log the connection status of a host"""
+    '''
+        Log the connection status of a host.
+
+        `host` IP or hostname of a server to query.
+
+        `timeout` Set the timeout in seconds to use for the connection test.
+
+        `filepath` Path to a the file where results should be appended to. Creates the file if it does not exist. If not specified, results are printed to stdout.
+    '''
 
     logline = f"[{datetime.now().strftime('%Y-%m-%d %H:%M:%S')}][{host}][{'OK' if isOnline(host, timeout) else 'FAIL'}]"
 
@@ -82,6 +102,11 @@ def log(host: str, timeout: int, filepath: None | str = None) -> None:
 
 
 def parseArgs(args: list[str]) -> argparse.Namespace:
+    '''
+        Parse command line arguments.
+
+        `args` List of user-supplied command line arguments.
+    '''
 
     parser = argparse.ArgumentParser(
         prog='outage_detector', description='Log outages and print statistics.'
@@ -122,7 +147,7 @@ def parseArgs(args: list[str]) -> argparse.Namespace:
     return parser.parse_args(args)
 
 
-def main():
+def main() -> None:
 
     args = parseArgs(sys.argv[1:])