Merge branch 'phpdoc' into piernov

1 files changed, 47 insertions, 3 deletions

diff --git a/inc/dungeon.inc b/inc/dungeon.inc
index d6b80fc..bf99685 100644
--- a/inc/dungeon.inc
+++ b/inc/dungeon.inc
@@ -1,12 +1,25 @@
 <?php
+/**
+ * Manages the dungeon.
+ *
+ * @package inc\dungeon.inc
+ * @author     Alexandre Renoux
+ * @author     Pierre-Emmanuel Novac
+ */
+
 require_once("messages.inc");
 require_once("account.inc");
 require_once("Monster.inc");
 require_once("perso.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();
@@ -22,16 +35,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"])) {
@@ -39,11 +68,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();
@@ -51,6 +85,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"];
@@ -59,6 +98,11 @@ function sendDungeonProgress(){
 	reusable();
 }
 
+/**
+ * Marks the dungeon as not accessible in the session.
+ *
+ * @return void
+ */
 
 function exitDungeon(){
 	$_SESSION["dungeon"] = false;