From 2fceb6c19dfa67f2afe2fff516c82613b8081d13 Mon Sep 17 00:00:00 2001
From: Chris-1010 <122332721@umail.ucc.ie>
Date: Sun, 2 Mar 2025 14:47:37 +0000
Subject: [PATCH] REFACTOR: Documentation for some Flask routes & `nginx.conf`

---
 nginx/nginx.conf                 |  4 +++-
 web_server/blueprints/streams.py | 28 ++++++++++++++++++++++++++--
 web_server/blueprints/user.py    |  3 ++-
 3 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/nginx/nginx.conf b/nginx/nginx.conf
index 80a301e..d1959cc 100644
--- a/nginx/nginx.conf
+++ b/nginx/nginx.conf
@@ -96,7 +96,8 @@ http {
         ## VoDs Location and thumbnails
         ## Contains MP4 files and PNG thumbnails
         location ~ ^/vods/(.+)/(.+\.(mp4|png))$ {
-             alias /user_data/vods/$1/$2;
+            alias /user_data/vods/$1/$2
+            # where $1 is the user's username and $2 is the thumbnail_name
 
              # The thumbnails should not be cacheable
              expires -1d;
@@ -105,6 +106,7 @@ http {
         ## Profile pictures location
         location ~ ^/user/(.+)/index.png$ {
             alias /user_data/profile_pictures/$1.png;
+            # where $1 is the user's username
 
             # The profile pictures should not be cacheable
             expires -1d;
diff --git a/web_server/blueprints/streams.py b/web_server/blueprints/streams.py
index f50b713..257203b 100644
--- a/web_server/blueprints/streams.py
+++ b/web_server/blueprints/streams.py
@@ -144,6 +144,12 @@ def following_your_categories():
 def user_live_status(username):
     """
     Returns a streamer's status, if they are live or not and their most recent stream (as a vod) (their current stream if live)
+    Returns:
+    {
+        "is_live": bool,
+        "most_recent_stream": dict,
+        "user_id": int
+    }
     """
     user_id = get_user_id(username)
 
@@ -154,8 +160,6 @@ def user_live_status(username):
     # If there is no most recent vod, set it to None
     if not most_recent_vod:
         most_recent_vod = None
-    else:
-        most_recent_vod = most_recent_vod['vod_id']
 
     return jsonify({
         "is_live": is_live,
@@ -165,10 +169,30 @@ def user_live_status(username):
 
 
 # VOD Routes
+@stream_bp.route('/vods/<int:vod_id>')
+def vod(vod_id):
+    """
+    Returns a JSON of a vod
+    """
+    vod = get_vod(vod_id)
+    return jsonify(vod)
+
 @stream_bp.route('/vods/<string:username>')
 def vods(username):
     """
     Returns a JSON of all the vods of a streamer
+    Returns:
+    [
+        {
+            "vod_id": int,
+            "title": str,
+            "datetime": str,
+            "category_name": str,
+            "length": int (in seconds),
+            "views": int
+        }
+    ]
+    
     """
     user_id = get_user_id(username)
     vods = get_user_vods(user_id)
diff --git a/web_server/blueprints/user.py b/web_server/blueprints/user.py
index 20d51f9..98e855f 100644
--- a/web_server/blueprints/user.py
+++ b/web_server/blueprints/user.py
@@ -45,6 +45,7 @@ def user_stream_key(username: str):
 def user_profile_picture_save():
     """
     Saves user profile picture
+    Returns the path to the saved image
     """
     username = session.get("username")
     thumbnail_path = path_manager.get_profile_picture_file_path(username)
@@ -58,7 +59,7 @@ def user_profile_picture_save():
     image.convert('RGB')
     image.save(thumbnail_path, "PNG")
 
-    return jsonify({"message": "Profile picture saved"})
+    return jsonify({"message": "Profile picture saved", "path": thumbnail_path})
 
 @login_required
 @user_bp.route('/user/same/<string:username>')