From 7ac3b76e6c802c66a6e9abce98ba70a8dcf033f8 Mon Sep 17 00:00:00 2001
From: Joachim Lusiardi <joachim@lusiardi.de>
Date: Sun, 17 Dec 2023 22:00:42 +0100
Subject: [PATCH] add some documentation

---
 src/artifacts.rs |  1 +
 src/game.rs      | 25 ++++++++++++++++++-------
 2 files changed, 19 insertions(+), 7 deletions(-)

diff --git a/src/artifacts.rs b/src/artifacts.rs
index 70589b2..3be167f 100644
--- a/src/artifacts.rs
+++ b/src/artifacts.rs
@@ -9,6 +9,7 @@ pub trait Artifact {
     fn get_immutable_position(&self) -> &Position;
     /// call to apply the effects of the artifact to the player
     fn collect(&mut self, player: &mut Player);
+    /// returns if the artifact was collected and can be removed from the level
     fn was_collected(&self) -> bool;
 }
 
diff --git a/src/game.rs b/src/game.rs
index 722d43b..4f7c3a9 100644
--- a/src/game.rs
+++ b/src/game.rs
@@ -1,15 +1,16 @@
-use crate::artifacts::Artifact;
 use crate::level::{Level, StructureElement};
 use crate::level_generator::LevelGenerator;
-use crate::monster::Monster;
 use crate::player::Player;
 use crate::position::Position;
 
 pub const LEVELS: usize = 2;
 
+/// the main structure to hold all information about the ongoing game
 pub struct Game {
-    pub player: Player,
-    pub levels: Vec<Level>,
+    /// the player
+    player: Player,
+    /// the levels of the game
+    levels: Vec<Level>,
 }
 
 impl Game {
@@ -38,6 +39,8 @@ impl Game {
     }
     pub fn get_level(&self, level: usize) -> &Level { &self.levels[level] }
     pub fn get_mutable_level(&mut self, level: usize) -> &mut Level { &mut self.levels[level] }
+    /// check if the player can move in the given direction. This only checks for structure element
+    /// limitation as walls.
     fn can_move(&mut self, dx: i16, dy: i16) -> bool {
         let player_pos = &self.player.get_position();
         let new_x: i16 = player_pos.get_x() as i16 + dx;
@@ -54,25 +57,32 @@ impl Game {
         };
         true
     }
+    /// returns the position (as tuple) of the next level's start point.
     fn next_start(&self) -> (usize, usize, usize) {
         let level = self.player.get_immutable_position().get_level() + 1;
         let (x, y) = self.levels[level].start;
         (level, x, y)
     }
+    /// returns the position (as tuple) of the previous level's end point.
     fn prev_end(&self) -> (usize, usize, usize) {
         let level = self.player.get_immutable_position().get_level() - 1;
         let (x, y) = self.levels[level].end;
         (level, x, y)
     }
-    fn next_element(&mut self, dx: i16, dy: i16) -> (Option<StructureElement>, Option<&mut Monster>, Option<&mut Box<(dyn Artifact + 'static)>>) {
+    /// get the next structure element sen from the player's position into the given direction.
+    fn next_element(&mut self, dx: i16, dy: i16) -> Option<StructureElement> {
         let player_pos = &self.player.get_position();
         let new_x: i16 = player_pos.get_x() as i16 + dx;
         let new_y: i16 = player_pos.get_y() as i16 + dy;
         let player_level = player_pos.get_level();
         let level = &mut self.levels[player_level];
-        level.get_element(new_x, new_y)
+        level.get_element(new_x, new_y).0
     }
 
+    /// move the game's player into the given direction. If on the target field there is a stair,
+    /// the player follows the stair up/down to the next level.
+    /// Discovery is performed on the new location of the player.
+    /// The returned value is the direction that will bring the player back to his original field.
     pub fn move_player(&mut self, mut dx: i16, mut dy: i16) -> (i16, i16) {
         // verify the player can do the move
         if !self.can_move(dx, dy) {
@@ -81,7 +91,7 @@ impl Game {
 
         let player_pos = &self.player.get_position();
         let mut player_level = player_pos.get_level();
-        let (structure, _, _) = self.next_element(dx, dy);
+        let structure = self.next_element(dx, dy);
 
         // use stairs if walked onto one
         match structure {
@@ -138,6 +148,7 @@ impl Game {
             }
         }
     }
+    /// updates the player's current level. This will remove collected artifacts and dead monsters.
     pub fn update_level(&mut self) {
         let player_pos = &self.player.get_immutable_position();
         let player_level = player_pos.get_level();