more documentation

src/artifacts.rs

@@ -6,6 +6,7 @@ use crate::position::Position;
 
 pub trait Artifact {
     //! An artifact that can be collected by the player
+    /// get the character and color used to draw the artifact into the level
     fn get_representation(&self) -> (&str, Color);
     /// get the position of the artifact in the level
     fn get_immutable_position(&self) -> &Position;
@@ -15,13 +16,17 @@ pub trait Artifact {
     fn was_collected(&self) -> bool;
 }
 
+/// An artifact that contains a random amount of gold pieces.
 pub struct Chest {
-    /// a chest that contains some gold
+    /// the chests position
     position: Position,
+    /// the chests value
     gold: usize,
 }
 
 impl Chest {
+    /// create a chest at the given position with a random amount of gold.
+    /// The gold amount depends on the level, the deeper you go, the more you get.
     pub fn new(position: Position) -> Self {
         let min_gold = 10 * (position.get_level() + 1);
         let max_gold = min_gold + 10 * position.get_level();
@@ -55,6 +60,7 @@ impl Artifact for Chest {
 }
 
 #[derive(Clone, Copy)]
+/// An artifact that gives the player some health on consumption.
 pub struct Potion {
     /// a potion that restores some health
     position: Position,
@@ -88,7 +94,10 @@ impl Artifact for Potion {
     }
 
     fn collect(&mut self, player: &mut Player, messages: &mut Vec<String>) {
-        // only consume potion of the player can gain at least one health point
+        //! called when the player walked on to a potion.
+        //!
+        //! Depending on health status and inventory usage the potion will
+        //! be consumed directly or moved to inventory.
         if !player.is_healthy() {
             let old = player.get_life();
             player.change_life(self.health.try_into().unwrap());

src/game.rs

@@ -22,6 +22,7 @@ pub struct Game {
     player: Player,
     /// the levels of the game
     levels: Vec<Level>,
+    /// messages that are displayed in the ui
     pub messages: Vec<String>,
 }