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);
-/// ::new() -> DbApi<'q> (Db finds a connection by itself, usefull for cli)
-/// ::with_conn(conn) -> DbApi<'q> (uses a user-defined connection)
-///  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_player()
+///          // Needs an action's history (one entry only should be enough)
+///  x       .undo_last_action() -> Success status
 ///  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,43 +156,47 @@ 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 {
-                executed: false,
-                response: None })
-        } else {
-            use schema::looted::dsl::*;
-            let loot_value = looted.find(loot_id)
-                .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),
-                    _ => Ok(ActionStatus {
-                                executed: false,
-                                response: None,
-                            }),
-                })
+            return Ok(ActionStatus::nop());
         }
-
+        use schema::looted::dsl::*;
+        let loot_value = looted.find(loot_id).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 => Ok(self.update_wealth(sell_value).unwrap()),
+                _ => Ok(ActionStatus {
+                            executed: false,
+                            response: None,
+                        }),
+            })
     }
 
     /// Adds the value in gold to the player's wealth.