From 8fb885729afae0d08eecba533737029c6f3f87c1 Mon Sep 17 00:00:00 2001
From: Jim Ewald <jim.ewald@gmail.com>
Date: Fri, 15 Dec 2017 11:09:51 -0800
Subject: [PATCH] Add documentation to user account creation process

---
 app/LocalUser/controllers.py | 32 ++++++++++++++++++++++++++++++--
 app/__init__.py              | 10 +++++++++-
 2 files changed, 39 insertions(+), 3 deletions(-)

diff --git a/app/LocalUser/controllers.py b/app/LocalUser/controllers.py
index e3ec51d..4757bbc 100644
--- a/app/LocalUser/controllers.py
+++ b/app/LocalUser/controllers.py
@@ -18,11 +18,26 @@
 
 
 class DoConfirm(Resource):
+    """
+    Confirm and activate a user account.
+
+    Args:
+        None
+
+    Returns:
+        A JSON document with the key 'success' set to True if the operation
+        is successful. Otherwise the key 'success' is set to False and the
+        field 'code' is set to the HTTP error code that represents a specific
+        reason when the account confirmation was rejected.
+
+    Raises:
+        None
+    """
 
     def post(self):
         # Get values
-        email = request.form.get('email')
-        token = request.form.get('token')
+        email = request.form.get('email')   # User account email address
+        token = request.form.get('token')   # Token assigned to account during account registration
 
         # Validate required fields
         validation = Validation()
@@ -52,9 +67,13 @@ def post(self):
             # Token is not for this user
             return {'success': False, 'code': 510}
 
+        # Set user account status to 'Confirmed'
         user.confirmed = True
 
+        # Delete the account confirmation token; it is no longer required
         db.session.delete(confirm_token)
+
+        # Commit the user account changes
         db.session.commit()
 
         logging.info('LocalUser-controller: DoConfirm: success: %s', user.id)
@@ -63,6 +82,15 @@ def post(self):
 
 
 class RequestConfirm(Resource):
+    """
+    Send account confirmation request email to user
+
+    Args:
+        param1: User account email address
+
+    Returns:
+        JSON document detailing the success or failure of the request.
+    """
 
     def get(self, email):
         # Get server URL
diff --git a/app/__init__.py b/app/__init__.py
index 2608dea..c5acf7f 100644
--- a/app/__init__.py
+++ b/app/__init__.py
@@ -25,7 +25,15 @@
 app = Flask(__name__)
 
 # Application version (major,minor,patch-level)
-version = "1.1.2"
+version = "1.1.3"
+
+"""
+Change Log
+
+1.1.3       Added documentation around the user account registration process.
+
+"""
+
 db = None
 
 # Load basic configurations