1 files changed, 46 insertions, 4 deletions

diff --git a/inc/dungeon.inc b/inc/dungeon.inc
index c023cf8..05dc57d 100644
--- a/inc/dungeon.inc
+++ b/inc/dungeon.inc
@@ -1,12 +1,23 @@
 <?php
+/**
+ * Manages the dungeon.
+ *
+ * @author     Alexandre Renoux
+ * @author     Pierre-Emmanuel Novac
+ */
+
 require_once("messages.inc");
 require_once("account.inc");
 require_once("Monster.inc");
 
-
+/**
+ * Loads all the dungeon's monsters from the XML file data/monsters.xml.
+ *
+ * @return array  contains all the Monster objects
+ */
 function generateMonster(){
 	$monsters = simplexml_load_file('data/monsters.xml');
-	$dungeon = array("cost"=>(string)$monsters["cost"],"monsters"=>array());
+	$dungeon = array("cost"=>(string)$monsters["cost"],"monsters"=>array()); //TODO: again, cost is a string?
 	foreach($monsters as $f){
 		$floor = (string)$f["name"];
 		$dungeon["monsters"][$floor] = array();
@@ -21,16 +32,32 @@ function generateMonster(){
 	return $dungeon;
 }
 
+/**
+ * Marks the dungeon as accessible in the session.
+ *
+ * @return void
+ */
 function initDungeon() {
-	$_SESSION["dungeon"]["access"] = true;
+	$_SESSION["dungeon"]["access"] = true; // TODO: is the $_SESSION["dungeon"] array useful (and created beforehand)?
 }
 
+/**
+ * Returns the dungeon array if it was created.
+ *
+ * @return array  dungeon array as created by generateMonster
+ */
 function sendDungeon() {
 	if(!empty($_SESSION["dungeon"]))
 		return $_SESSION["dungeon"];
 	else return false;
 }
 
+/**
+ * Allows acces to the dungeon in the session and sends it to the client.
+ * Debits the dungeon's ticket cost from the player's gold.
+ *
+ * @return void
+ */
 function buildDungeon() {
 	$dungeon=generateMonster();
 	if(!empty($_SESSION["dungeon"])) {
@@ -38,11 +65,16 @@ function buildDungeon() {
 	}
 	elseif(debitAccount($dungeon["cost"])) {
 		initDungeon();
-		$_SESSION["mine"]["gold"] -= $dungeon["cost"];
+		$_SESSION["mine"]["gold"] -= $dungeon["cost"]; // TODO: Account was already debited
 		echo json_encode($dungeon);
 	}
 }
 
+/**
+ * Sends monsters for a specific floor as specified by the floor POST parameter to the client.
+ *
+ * @return void
+ */
 function launchDungeon(){
 	$f= $_POST["floor"];
 	$dungeon=generateMonster();
@@ -50,6 +82,11 @@ function launchDungeon(){
 	echo json_encode($opponent);
 }
 
+/**
+ * Updates floor and monster number from the POST parameters in the session.
+ *
+ * @return void
+ */
 function sendDungeonProgress(){
 	$f= $_POST["floor"];
 	$nb=$_POST["mob"];
@@ -57,6 +94,11 @@ function sendDungeonProgress(){
 	$_SESSION["dungeon"]["mob"] = $nb;
 }
 
+/**
+ * Marks the dungeon as not accessible in the session.
+ *
+ * @return void
+ */
 
 function exitDungeon(){
 	$_SESSION["dungeon"] = false;