From 99404543b3f94e85a0defd176127f3f674d60998 Mon Sep 17 00:00:00 2001
From: Artus <artus@landoftheunicorn.ovh>
Date: Sat, 22 Jun 2019 15:46:57 +0200
Subject: [PATCH] adds documentation

---
 src/api.rs  | 54 ++++++++++++++++++++++++++++++++++++++++++++++-------
 src/main.rs |  4 ++++
 2 files changed, 51 insertions(+), 7 deletions(-)

diff --git a/src/api.rs b/src/api.rs
index aee1544..ae8e65d 100644
--- a/src/api.rs
+++ b/src/api.rs
@@ -1,25 +1,46 @@
 use actix_web::{web, web::Json, Error, HttpResponse, Result};
 use futures::Future;
 
-use lootalot_db::Pool;
-use lootalot_db::{ActionResult, DbConnection, Item, Player, QueryResult};
+use lootalot_db::{Pool, DbConnection, QueryResult, ActionResult};
+use lootalot_db::{Item, Player};
 
+/// A wrapper providing an API over the database
+/// It offers a convenient way to deal with connection
 pub struct DbApi<'q>(&'q DbConnection);
 
 impl<'q> DbApi<'q> {
+    /// Returns a DbApi using the user given connection
+    ///
+    /// # Usage
+    /// ```
+    /// let conn = DbConnection::establish();
+    /// let api = DbApi::with_conn(&conn);
+    /// ```
     pub fn with_conn(conn: &'q DbConnection) -> Self {
         Self(conn)
     }
-
+    /// Fetch the list of all players
+    ///
+    /// This method consumes the DbApi object.
     pub fn fetch_players(self) -> QueryResult<Vec<Player>> {
         Player::fetch_list(self.0)
     }
-
+    /// Wrapper for acting as a specific player
+    ///
+    /// The DbApi is moved inside a new AsPlayer object.
+    ///
+    /// # Usage
+    /// ```
+    /// let player_id: i32 = 1; // Id that references player in DB
+    /// let player = api.as_player(player_id);
+    /// ```
     pub fn as_player(self, id: i32) -> AsPlayer<'q> {
         AsPlayer { id, conn: self.0 }
     }
 }
 
+/// A wrapper for interactions of players with the database
+/// Possible actions are exposed as methods
 pub struct AsPlayer<'q> {
     id: i32,
     conn: &'q DbConnection,
@@ -30,6 +51,7 @@ impl<'q> AsPlayer<'q> {
     pub fn loot(self) -> QueryResult<Vec<Item>> {
         Player::fetch_loot(self.id, self.conn)
     }
+    /// Put a claim on a specific item
     pub fn claim(self, item: i32) -> ActionResult {
         Player::action_claim_object(self.id, item, self.conn)
     }
@@ -49,9 +71,27 @@ impl<'q> AsPlayer<'q> {
 //          .resolve_claims()
 //
 
-// fn db_call(f: fn(DbApi) -> ApiResponse) { ... }
-// ApiResponse needs to be Serialize
-
+/// Wraps call to the DbApi and process its result as a async HttpResponse
+///
+/// Provides a convenient way to call the api inside a route definition. Given a connection pool,
+/// access to the api is granted in a closure. The closure is called in a blocking way and should
+/// return a QueryResult.
+/// If the query succeeds, it's result is returned as JSON data. Otherwise, an InternalServerError
+/// is returned.
+///
+/// # Usage
+/// ```
+///     (...)
+///     .route("path/to/",
+///         move |pool: web::Data<Pool>| {
+///             // user data can be processed here
+///             // ...
+///             db_call(pool, move |api| {
+///                 // ...do what you want with the api
+///             }
+///         }
+///     )
+/// ```
 pub fn db_call<
     J: serde::ser::Serialize + Send + 'static,
     Q: Fn(DbApi) -> QueryResult<J> + Send + 'static,
diff --git a/src/main.rs b/src/main.rs
index 6c266bf..ff2c1f6 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -9,5 +9,9 @@ mod server;
 fn main() {
     env_logger::init();
     dotenv::dotenv().ok();
+    // TODO: Build a cli app with complete support of DbApi
+    //       Server is started with 'serve' subcommand
+    //       $ lootalot serve
+    // Start the server.
     server::serve();
 }