From 456b72cab75c57612eb38a36070981de216f28d4 Mon Sep 17 00:00:00 2001
From: Wambaforestin <wambaforestin@gmail.com>
Date: Sat, 14 Dec 2024 18:49:17 +0100
Subject: [PATCH] Add docstrings to authentication module functions for
 improved clarity and maintainability

---
 document_analysis/document_analysis/auth.py | 51 ++++++++++++++++-----
 1 file changed, 39 insertions(+), 12 deletions(-)

diff --git a/document_analysis/document_analysis/auth.py b/document_analysis/document_analysis/auth.py
index 800b53d..eb08a87 100644
--- a/document_analysis/document_analysis/auth.py
+++ b/document_analysis/document_analysis/auth.py
@@ -1,22 +1,32 @@
-import functools
+import functools # The functools module in Python deals with higher-order functions, simple terms they are functions which take other functions as arguments. The primary object that the functools module deals with is the decorator, which is a function that wraps another function or method. The primary purpose of decorators is to modify or extend the behavior of functions or methods. The functools module provides several functions that can be used to create decorators. The module also provides a few other higher-order functions, which are used to manipulate or create other functions.
 from flask import (
     Blueprint, flash, g, redirect, render_template, request, session, url_for
 )
-from werkzeug.security import check_password_hash, generate_password_hash
+from werkzeug.security import check_password_hash, generate_password_hash 
 from document_analysis.db import get_db
 
-bp = Blueprint('auth', __name__, url_prefix='/auth')
+bp = Blueprint('auth', __name__, url_prefix='/auth') # Create a Blueprint named 'auth' with the name of the current module (__name__) and the URL prefix '/auth'.
 
 def login_required(view):
-    @functools.wraps(view)
+    """It's a decorator that will redirect to the login page if the user is not logged in.
+
+    Args:
+        view (function): The view function to be decorated.
+
+    Returns:
+        function: The wrapped view function that includes the login check.
+    """
+    @functools.wraps(view) # The functools.wraps() function is a decorator that takes a function used in a decorator and adds the functionality of copying over the function name, docstring, arguments list, etc. This allows you to wrap a function in a decorator without losing the information of the original function.
     def wrapped_view(**kwargs):
-        if g.user is None:
+        if g.user is None: # g is a special object that is unique for each request. It is used to store data that might be accessed by multiple functions during the request. The connection is stored and reused instead of creating a new connection if get_db is called a second time in the same request.
             return redirect(url_for('auth.login'))
         return view(**kwargs)
     return wrapped_view
 
-@bp.before_app_request
-def load_logged_in_user():
+@bp.before_app_request # Register a function that runs before the view function, no matter what URL is requested. This is used to load a user from the session.
+def load_logged_in_user(): 
+    """It's a function that loads the logged in user from the session.
+    """
     user_id = session.get('user_id')
     
     if user_id is None:
@@ -26,8 +36,13 @@ def load_logged_in_user():
             'SELECT * FROM user WHERE id = ?', (user_id,)
         ).fetchone()
 
-@bp.route('/register', methods=('GET', 'POST'))
+@bp.route('/register', methods=('GET', 'POST')) # Register a new view function for the '/register' URL that accepts both GET and POST requests.
 def register():
+    """It's a view function that registers a new user.
+
+    Returns:
+        str: It returns the rendered template of the register.html file.
+    """
     if request.method == 'POST':
         username = request.form['username']
         password = request.form['password']
@@ -52,11 +67,17 @@ def register():
             return redirect(url_for('auth.login'))
 
         flash(error)
-
+        
+    # If the request method is GET or the data is invalid, the register page should be shown.
     return render_template('auth/register.html')
 
-@bp.route('/login', methods=('GET', 'POST'))
+@bp.route('/login', methods=('GET', 'POST')) # Register a new view function for the '/login' URL that accepts both GET and POST requests.
 def login():
+    """It's a view function that logs in a user.
+
+    Returns:
+        str: It returns the rendered template of the login.html file.
+    """
     if request.method == 'POST':
         username = request.form['username']
         password = request.form['password']
@@ -77,10 +98,16 @@ def login():
             return redirect(url_for('index'))
 
         flash(error)
-
+        
+    # If the request method is GET or the data is invalid, the login page should be shown.
     return render_template('auth/login.html')
 
-@bp.route('/logout')
+@bp.route('/logout') # Register a new view function for the '/logout' URL.
 def logout():
+    """It's a view function that logs out a user.
+
+    Returns:
+        str: It redirects the user to the index page.
+    """
     session.clear()
     return redirect(url_for('index'))
\ No newline at end of file