Add some docs

compendium_v2/routes/authentication.py

@@ -16,6 +16,11 @@ def before_request():
 
 @routes.route('/login')
 def login():
+    """
+    Handler for login requests. Implements an OAuth2 Authorization Code Flow, redirecting to the provider's login page.
+
+    :return: redirect to the provider's login page, with a redirect_uri to /authorize
+    """
     client = get_client()
 
     # _external uses headers to determine the full URL when behind a reverse proxy
@@ -25,6 +30,13 @@ def login():
 
 @routes.route('/authorize')
 def authorize():
+    """
+    Handler for /authorize requests. This is the redirect_uri for the OAuth2 Authorization Code Flow.
+    Checks the user's response from the provider, and logs in + creates a local user & session management if successful.
+    Once a user is returned by the provider, session and user management is handled entirely within the application.
+
+    :return: redirect to / if successful, or a 400 response if the user response is invalid
+    """
     client = get_client()
     token = client.authorize_access_token()
 
@@ -45,7 +57,13 @@ def authorize():
 
 @routes.route("/logout")
 def logout():
-    # The user will be logged out of the application, but not the IDP.
-    # If they visit again before their oauth token expires, they are immediately logged in.
+    """
+    Handler for /logout requests. Logs the user out of the application.
+
+    The user will be logged out of the application, but not the IDP.
+    If they visit again before their oauth token expires, they are immediately logged in.
+
+    :return: redirect to the survey index
+    """
     logout_user()
     return redirect(url_for('compendium-v2-default.survey_index'))

compendium_v2/routes/default.py

@@ -32,6 +32,12 @@ def after_request(resp):
 @routes.route('/', defaults={'path': ''}, methods=['GET'])
 @routes.route('/<path:path>', methods=['GET'])
 def index(path):
+    """
+    Default route handler for the SPA.
+
+    :param path: the path of the request
+    :return: the index.html template or a 404 response for invalid API requests
+    """
     is_api = path.startswith('api')
 
     if is_api:
@@ -47,6 +53,12 @@ def index(path):
 @routes.route('/survey/', defaults={'path': ''}, methods=['GET'])
 @routes.route('/survey/<path:path>', methods=['GET'])
 def survey_index(path):
+    """
+    Default route handler for the survey SPA.
+
+    :param path: the path of the request
+    :return: the index.html template or a 404 response for invalid Survey API requests
+    """
     is_api = path.startswith('api')
 
     if is_api: