adds doc

lootalot_db/src/lib.rs

@@ -67,22 +67,15 @@ impl<T: Default + serde::Serialize> ActionStatus<T> {
 ///
 /// # Todo list
 /// ```text
-/// struct DbApi<'q>(&'q DbConnection);
+///  v  .as_player()
-/// ::new() -> DbApi<'q> (Db finds a connection by itself, usefull for cli)
+///          // Needs an action's history (one entry only should be enough)
-/// ::with_conn(conn) -> DbApi<'q> (uses a user-defined connection)
+///  x       .undo_last_action() -> Success status
-///  v  .fetch_players()
-///  v  .fetch_inventory()
-///  v  .fetch_claims()
-///  v  .as_player(player_id) -> AsPlayer<'q>
-///  v       .loot() -> List of items owned (Vec<Item>)
-///  v       .claim(loot_id) -> Success status (bool)
-///  v       .unclaim(loot_id) -> Success status (bool)
-///  v       .sell(loot_id) -> Success status (bool, earned)
-///  v       .buy(item_desc) -> Success status (bool, cost)
-///  v       .update_wealth(value_in_gold) -> Success status (bool, new_wealth)
 ///  v  .as_admin()
-///  x       .add_loot(identifier, [items_desc]) -> Success status
+///          // When adding loot, an identifier should be used to build some kind of history
+///  vx      .add_loot(identifier, [items_desc]) -> Success status
 ///  x       .sell_loot([players], [excluded_item_ids]) -> Success status (bool, player_share)
+///  // Claims should be resolved after a certain delay
+///  x       .set_claims_timeout()
 ///  x       .resolve_claims()
 ///  v       .add_player(player_data)
 /// ```
@@ -163,36 +156,42 @@ impl<'q> AsPlayer<'q> {
     /// Buy an item and add it to this player chest
     ///
     /// TODO: Items should be picked from a custom list
+    ///
+    /// # Panics
+    ///
+    /// This currently panics if player wealth fails to be updated, as this is
+    /// a serious error. TODO: handle deletion of bought item in case of wealth update failure.
     pub fn buy<'a>(self, name: &'a str, price: i32) -> ActionResult<Option<(i32, i32, i32, i32)>> {
         let new_item = models::item::NewLoot::to_player(self.id, (name, price));
         diesel::insert_into(schema::looted::table)
             .values(&new_item)
             .execute(self.conn)
             .and_then(|r| match r {
-                1 => self.update_wealth(-(price as f32)),
+                1 => Ok(self.update_wealth(-(price as f32)).unwrap()),
                 _ => Ok(ActionStatus::nop())
             })
     }
     /// Sell an item from this player chest
+    ///
+    /// # Panics
+    ///
+    /// This currently panics if player wealth fails to be updated, as this is
+    /// a serious error. TODO: handle restoring of sold item in case of wealth update failure.
     pub fn sell(self, loot_id: i32, _price_mod: Option<f32>) -> ActionResult<Option<(i32, i32, i32, i32)>> {
         // Check that the item belongs to player
         let exists_and_owned: bool = diesel::select(models::Loot::owns(self.id, loot_id))
             .get_result(self.conn)?;
         if !exists_and_owned {
-            Ok(ActionStatus {
+            return Ok(ActionStatus::nop());
-                executed: false,
+        }
-                response: None })
-        } else {
         use schema::looted::dsl::*;
-            let loot_value = looted.find(loot_id)
+        let loot_value = looted.find(loot_id).select(base_price).first::<i32>(self.conn)?;
-                .select(base_price)
-                .first::<i32>(self.conn)?;
         let sell_value = (loot_value / 2) as f32;
         diesel::delete(looted.find(loot_id))
             .execute(self.conn)
             .and_then(|r| match r {
                 // On deletion, update this player wealth
-                    1 => self.update_wealth(sell_value),
+                1 => Ok(self.update_wealth(sell_value).unwrap()),
                 _ => Ok(ActionStatus {
                             executed: false,
                             response: None,
@@ -200,8 +199,6 @@ impl<'q> AsPlayer<'q> {
             })
     }
 
-    }
-
     /// Adds the value in gold to the player's wealth.
     ///
     /// Value can be negative to substract wealth.