From 216d71c15d653bb8bbcca0a5f5efbe62b22db7e9 Mon Sep 17 00:00:00 2001
From: Luke Else <mail@luke-else.co.uk>
Date: Mon, 22 Jan 2024 08:33:28 +0000
Subject: [PATCH] Continuing to add correct documentation to components within
 the application

---
 controllers/database/database.py | 26 +++++++++++++++++++++++---
 controllers/web/user.py          | 18 +++++++++---------
 2 files changed, 32 insertions(+), 12 deletions(-)

diff --git a/controllers/database/database.py b/controllers/database/database.py
index 86970aa..fe0fc66 100644
--- a/controllers/database/database.py
+++ b/controllers/database/database.py
@@ -5,6 +5,10 @@ import os
 
 
 class DatabaseController(ABC):
+    """ Abstract Base Class to handle database access for each component
+        in the web app
+    """
+
     __data_dir = "./data/"
     __db_name = "wmgzon.db"
 
@@ -15,6 +19,9 @@ class DatabaseController(ABC):
     __sqlitefile = __data_dir + __db_name
 
     def __init__(self):
+        """ Initialises the object and creates a connection to the local
+            DB on the server
+        """
         self._conn = None
         try:
             # Creates a connection and specifies a flag to parse all types
@@ -28,13 +35,14 @@ class DatabaseController(ABC):
             print(e)
 
     def __del__(self):
+        """ Object Destructor which kills the connection to the database """
         if self._conn is not None:
             self._conn.close()
 
-    """ Takes a dictionary of fields and returns the object
-        with those fields populated """
-
     def new_instance(self, of: type, with_fields: Mapping[str, Any]):
+        """ Takes a dictionary of fields and returns the object
+            with those fields populated
+        """
         obj = of.__new__(of)
         for attr, value in with_fields.items():
             setattr(obj, attr, value)
@@ -46,16 +54,28 @@ class DatabaseController(ABC):
 
     @abstractmethod
     def create(self):
+        """ Abstract method used to create a new record of a given
+            type within the database
+        """
         pass
 
     @abstractmethod
     def read(self):
+        """ Abstract method used to read a record of a given
+            type from the database
+        """
         pass
 
     @abstractmethod
     def update(self):
+        """ Abstract method used to update a record of a given
+            type within the database
+        """
         pass
 
     @abstractmethod
     def delete(self):
+        """ Abstract method used to delete record of a given
+            type from the database
+        """
         pass
diff --git a/controllers/web/user.py b/controllers/web/user.py
index 8efb15b..7b15240 100644
--- a/controllers/web/user.py
+++ b/controllers/web/user.py
@@ -1,3 +1,6 @@
+""" The user controller to manage all of the user related endpoints
+    in the web app
+"""
 from flask import Blueprint
 
 from flask import render_template, redirect, request, session, flash
@@ -10,19 +13,17 @@ from hashlib import sha512
 # Blueprint to append user endpoints to
 blueprint = Blueprint("users", __name__)
 
+
 # LOGIN FUNCTIONALITY
-# Function responsible for delivering the Login page for the site
-
-
 @blueprint.route('/login')
 def display_login():
+    """ Function responsible for delivering the Login page for the site """
     return render_template('index.html', content="login.html")
 
-# Function responsible for handling logins to the site
-
 
 @blueprint.post('/login')
 def login():
+    """ Function to handle the backend processing of a login request """
     database = UserController()
     user = database.read(request.form['username'])
     error = None
@@ -44,16 +45,15 @@ def login():
 
 
 # SIGNUP FUNCTIONALITY
-# Function responsible for delivering the Signup page for the site
 @blueprint.route('/signup')
 def display_signup():
+    """ Function responsible for delivering the Signup page for the site """
     return render_template('index.html', content="signup.html")
 
-# Function responsible for handling signups to the site
-
 
 @blueprint.post('/signup')
 def signup():
+    """ Function to handle the backend processing of a signup request """
     database = UserController()
 
     # User already exists
@@ -91,9 +91,9 @@ def signup():
 
 
 # SIGN OUT FUNCTIONALITY
-# Function responsible for handling logouts from the site
 @blueprint.route('/logout')
 def logout():
+    """ Function responsible for handling logouts from the site """
     # Clear the current user from the session if they are logged in
     session.pop('user_id', None)
     return redirect("/")