From 066659c26671ee3f8b417cf407d276c559b9f8b1 Mon Sep 17 00:00:00 2001
From: Luke Else <mail@luke-else.co.uk>
Date: Mon, 22 Jan 2024 08:21:40 +0000
Subject: [PATCH] Added correct documentation on the product controller... rest
 to follow

---
 controllers/web/product.py | 28 +++++++++++++++++-----------
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/controllers/web/product.py b/controllers/web/product.py
index 5513bae..c35db7e 100644
--- a/controllers/web/product.py
+++ b/controllers/web/product.py
@@ -1,3 +1,8 @@
+"""
+    Product related endpoints. Included contexts for principles such as
+    categories and image processing.
+"""
+
 from flask import Blueprint
 
 from flask import render_template, session, flash, request, redirect
@@ -17,27 +22,28 @@ ALLOWED_EXTENSIONS = {'png', 'jpg', 'jpeg', 'gif'}
 
 
 def allowed_file(filename):
+    """ Ensures only filenames ending with the correct extension are allowed.
+        Note: This does not verify that the content inside of the file
+        matches the type specified
+    """
     return '.' in filename and \
            filename.rsplit('.', 1)[1].lower() in ALLOWED_EXTENSIONS
 
 
 blueprint = Blueprint("products", __name__, url_prefix="/products")
 
-# Global context to enable the categories to be accessed
-# from any view
-
 
 @blueprint.context_processor
 def category_list():
+    """ Places a list of all categories in the products context """
     database = CategoryController()
     categories = database.read_all()
     return dict(categories=categories)
 
-# Loads the front product page
-
 
 @blueprint.route('/')
 def index():
+    """ The front product page """
     database = ProductController()
     products = database.read_all()
 
@@ -50,11 +56,10 @@ def index():
                            products=products
                            )
 
-# Loads a given product category page
-
 
 @blueprint.route('/<string:category>')
 def category(category: str):
+    """ Loads a given categories page """
     database = ProductController()
 
     # Check to see if there is a custome search term
@@ -75,17 +80,16 @@ def category(category: str):
                            category=category
                            )
 
-# Loads a given product based on ID
-
 
 @blueprint.route('/<int:id>')
 def id(id: int):
+    """ Loads a given product based on ID """
     return "ID: " + str(id)
 
 
-# Launches the page to add a new product to the site
 @blueprint.route('/add')
 def display_add_product():
+    """ Launches the page to add a new product to the site """
     user_id = session.get('user_id')
 
     # User must be logged in to view this page
@@ -102,9 +106,11 @@ def display_add_product():
     return render_template('index.html', content='new_product.html')
 
 
-# Processes a request to add a new product to the site
 @blueprint.post('/add')
 def add_product():
+    """ Server site processing to handle a request to add a
+        new product to the site
+    """
     user_id = session.get('user_id')
 
     # User must be logged in to view this page