From 7411bd44309f434d23546bd2798c452e348597ae Mon Sep 17 00:00:00 2001
From: BurnyLlama <burnyllama@protonmail.com>
Date: Sun, 16 Apr 2023 14:36:42 +0200
Subject: [PATCH] Added some documentation....

---
 src/database/mod.rs                  | 2 ++
 src/database/models/map.rs           | 9 +++++++++
 src/database/models/race.rs          | 6 ++++++
 src/database/models/search_result.rs | 5 ++++-
 src/database/models/teamrace.rs      | 6 ++++++
 5 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/src/database/mod.rs b/src/database/mod.rs
index 5d25e54..a45d330 100644
--- a/src/database/mod.rs
+++ b/src/database/mod.rs
@@ -4,6 +4,8 @@ use std::{env, error::Error};
 
 pub mod models;
 
+/// DatabaseHandler is a struct that can hold a database connection pool.
+/// TODO: This might actually be an unnecessary abstraction, however it is 0-cost I believe...
 pub struct DatabaseHandler {
     pub pool: PgPool,
 }
diff --git a/src/database/models/map.rs b/src/database/models/map.rs
index 8bcb738..abf71f8 100644
--- a/src/database/models/map.rs
+++ b/src/database/models/map.rs
@@ -17,18 +17,24 @@ pub struct Map {
 }
 
 impl Map {
+    /// This gets all maps in the map database.
     pub async fn get_all_maps(db: &DatabaseHandler) -> Result<Vec<Map>, sqlx::Error> {
         sqlx::query_file_as!(Map, "sql/maps/get_all_maps.sql")
             .fetch_all(&db.pool)
             .await
     }
 
+    /// This gets a map from the database via its name.
+    /// Returns an Err<sqlx::Error> if no map exists with the given name.
     pub async fn get_map_by_name(db: &DatabaseHandler, map: &str) -> Result<Map, sqlx::Error> {
         sqlx::query_file_as!(Map, "sql/maps/get_map_by_name.sql", map)
             .fetch_one(&db.pool)
             .await
     }
 
+    /// This gets all maps from the database via their category.
+    /// Valid values are: Novice, Moderate, Brutal, Insane, Dummy, DDmaX.Easy, DDmaX.Next, DDmaX.Pro, DDmaX.Nut, Oldschool, Solo, Race, Fun
+    /// FIXME: Returns an empty array on invalid category!
     pub async fn get_maps_by_category(
         db: &DatabaseHandler,
         category: &str,
@@ -38,6 +44,9 @@ impl Map {
             .await
     }
 
+    /// This gets all the maps in the database made by a specific mapper.
+    /// Mappers are stored as an array, so if that array contains the given mapper, the entry is returned.
+    /// FIXME: Returns an empty array on non-existant mapper!
     pub async fn get_maps_by_mapper(
         db: &DatabaseHandler,
         mapper: &str,
diff --git a/src/database/models/race.rs b/src/database/models/race.rs
index b651d27..b193fad 100644
--- a/src/database/models/race.rs
+++ b/src/database/models/race.rs
@@ -18,6 +18,9 @@ pub struct Race {
 }
 
 impl Race {
+    /// This gets all the races from the database by a given player.
+    /// It is paginated into a SearchResult<Race>!
+    /// FIXME: Returns empty array for non-existent player.
     pub async fn get_races_by_player(
         db: &DatabaseHandler,
         player: &str,
@@ -50,6 +53,9 @@ impl Race {
         })
     }
 
+    /// This gets all the races from the database on a specific map.
+    /// It is paginated into a SearchResult<Race>!
+    /// FIXME: Returns empty array for non-existent map.
     pub async fn get_races_by_map(
         db: &DatabaseHandler,
         map: &str,
diff --git a/src/database/models/search_result.rs b/src/database/models/search_result.rs
index e84b78f..803d748 100644
--- a/src/database/models/search_result.rs
+++ b/src/database/models/search_result.rs
@@ -1,5 +1,6 @@
 use serde::{Deserialize, Serialize};
 
+/// This is a generic struct that represents a page of content that has been paginated.
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct SearchResult<T> {
     pub results: Vec<T>,
@@ -10,7 +11,9 @@ pub struct SearchResult<T> {
 /// This constant should be used everywhere so that it can easily changed.
 pub const ROWS_PER_PAGE: i32 = 200;
 
-/// This gets an i32 from an Option<&str>. It is very fail safe of any bad value, where it will return 1 instead of an error.
+/// This gets an i32 from an Option<&str>.
+/// It is fail safe: for any "bad" value, it will return 1 instead of an error.
+/// TODO: Maybe this should be an error instead...
 pub fn get_page_number_as_i32_from_str(page_as_str: Option<&str>) -> i32 {
     str::parse(page_as_str.unwrap_or("1")).unwrap_or(1)
 }
diff --git a/src/database/models/teamrace.rs b/src/database/models/teamrace.rs
index a6b79c3..38511b7 100644
--- a/src/database/models/teamrace.rs
+++ b/src/database/models/teamrace.rs
@@ -14,6 +14,9 @@ pub struct Teamrace {
 }
 
 impl Teamrace {
+    /// This gets all the teamraces from the database a given player has partaken in.
+    /// It is paginated into a SearchResult<Teamrace>!
+    /// FIXME: Returns empty array for non-existent player.
     pub async fn get_teamraces_by_player(
         db: &DatabaseHandler,
         player: &str,
@@ -46,6 +49,9 @@ impl Teamrace {
         })
     }
 
+    /// This gets all the teamraces from the database on a specific map.
+    /// It is paginated into a SearchResult<Teamrace>!
+    /// FIXME: Returns empty array for non-existent map.
     pub async fn get_teamraces_by_map(
         db: &DatabaseHandler,
         map: &str,