Merge branch 'phpdoc' into piernov

12 files changed, 491 insertions, 16 deletions

diff --git a/inc/Inventory.inc b/inc/Inventory.inc
index 3e0137d..4a1add8 100644
--- a/inc/Inventory.inc
+++ b/inc/Inventory.inc
@@ -2,18 +2,44 @@
 
 require_once("perso.inc");
 
+/**
+ * Represent the player's Inventory.
+ * Implemented as a singleton in the session.
+ *
+ * @package inc\Inventory.inc
+ * @author     Alexandre Renoux
+ * @author     Pierre-Emmanuel Novac
+ */
 class Inventory {
-
+	/**
+	 * @var array  Arrays of array with Item object and Item's count as int
+	 */
 	public $items = array();
 
+	/**
+	 * Checks if the Inventory was already created in the session
+	 * 
+	 * @return boolean  true if Inventory was already created, false otherwise
+	 */
 	public static function created() {
 		return !empty($_SESSION["inventory"]);
 	}
 
+	/**
+	 * Returns the Inventory's content from the session.
+	 * 
+	 * @return array  array of Items and number
+	 */
 	public static function sendContent() {
 		return self::get()->items;
 	}
 
+	/**
+	 * Returns the Inventory from the session.
+	 * Implements the singleton pattern.
+	 * 
+	 * @return Inventory  the Inventory object
+	 */
 	public static function get() {
 		if(!self::created()) {
 			$_SESSION["inventory"] = new Inventory();
@@ -21,6 +47,12 @@ class Inventory {
 		return $_SESSION["inventory"];
 	}
 
+	/**
+	 * Adds an Item object to the Inventory, incrementing the Item's count if it was already present.
+	 * 
+	 * @param Item $item  Item to add to the Inventory
+	 * @return array  Item and Item's count
+	 */
 	private function _addItem($item) {
 		foreach($this->items as $k => $object){
 			if($object[0] == $item){
@@ -33,12 +65,24 @@ class Inventory {
 		return $tab;
 	}
 
+	/**
+	 * Adds an Item object to the singleton's Inventory from session.
+	 * 
+	 * @param Item $item  Item to add to the Inventory
+	 * @return array  Item and Item's count
+	 */
 	public static function addItem($item) {
 		$inv = self::get();
 		$tab = $inv->_addItem($item);
 		return $tab;
 	}
 
+	/**
+	 * Removes an Item object from the Inventory, not taking into account the Item's count.
+	 * 
+	 * @param Item $item  Item to remove from the Inventory
+	 * @return void
+	 */
 	private function _removeItem($item) {
 		foreach($this->items as $k => $object) {
 			if($object[0] == $item) {
@@ -48,11 +92,23 @@ class Inventory {
 		}
 	}
 
+	/**
+	 * Removes an Item object to the singleton's Inventory from session, not taking into account the Item's count.
+	 * 
+	 * @param Item $item  Item to remove from the Inventory
+	 * @return void
+	 */
 	public static function removeItem($item) {
 		$inv = self::get();
 		$inv->_removeItem($item);
 	}
 
+	/**
+	 * Consumes an Item object from the Inventory, decrementing the Item's count and removing it if count reaches 0.
+	 * 
+	 * @param Item $item  Item to consume from the Inventory
+	 * @return array|false  Item and updated Item's count, false if it was not found
+	 */
 	private function _useItem($item) {
 		foreach($this->items as $k => $object){
 			if($object[0] == $item) {
@@ -70,12 +126,24 @@ class Inventory {
 		return false;
 	}
 
+	/**
+	 * Consumes an Item object to the singleton's Inventory from session, decrementing the Item's count and removing it if count reaches 0.
+	 * 
+	 * @param Item $item  Item to consume from the Inventory
+	 * @return array|false  Item and updated Item's count, false if it was not found
+	 */
 	public static function useItem($item) {
 		$inv = self::get();
 		$it = $inv->_useItem($item);
 		return $it;
 	}
 
+	/**
+	 * Generates an XML tree describing the Inventory
+	 *
+	 * @param SimpleXMLElement $root  root XML element to add the Inventory's Items to
+	 * @return void
+	 */
 	public function addToXML($root) {
 		foreach($this->items as $item)
 			$item[0]->addToXML($root, $item[1]);
diff --git a/inc/Item.inc b/inc/Item.inc
index a8ee302..435ca1c 100644
--- a/inc/Item.inc
+++ b/inc/Item.inc
@@ -2,13 +2,50 @@
 
 require_once("perso.inc");
 
+/**
+ * Represent an Item in the shop or in the Inventory.
+ *
+ * @package inc\Item.inc
+ * @author     Alexandre Renoux
+ * @author     Pierre-Emmanuel Novac
+ */
 class Item {
+
+	/**
+	 * @var string  Name of the item.
+	 */
 	public $name = "";
+
+	/**
+	 * @var int  Item's cost.
+	 */
 	public $cost = 0;
+
+	/**
+	 * @var string  Item's icon.
+	 */
 	public $icon = "";
+
+	/**
+	 * @var string  Item's description.
+	 */
 	public $desc = "";
+
+	/**
+	 * @var array  Item's features as an associative array
+	 */
 	public $feat = array();
 
+	/**
+	 * Item's constructor
+	 *
+	 * @param string $name  Item's name
+	 * @param int $cost     Item's cost
+	 * @param string $icon  Item's icon
+	 * @param string $desc  Item's description
+	 * @param array $feat   associative array of strings describing the Item's features
+	 * @return void
+	 */
 	function __construct($name, $cost, $icon, $desc, $feat) {
 		$this->name = $name;
 		$this->cost = $cost;
@@ -17,6 +54,11 @@ class Item {
 		$this->feat = $feat;
 	}
 
+	/**
+	 * Applies Item's features on the player.
+	 *
+	 * @return void
+	 */
 	function consume() {
 		foreach($this->feat as $k => $v) {
 			switch($k) {
@@ -26,6 +68,13 @@ class Item {
 		}
 	}
 
+	/**
+	 * Generates an XML tree describing the Item
+	 *
+	 * @param SimpleXMLElement $xml  root XML element to add the Item's property to
+	 * @param int $count             numbers of Items
+	 * @return void
+	 */
 	function addToXML($root, $count) {
 		$item = $root->addChild("item");
 		$item->addChild("name", $this->name);
@@ -38,12 +87,18 @@ class Item {
 		$item->addChild("count", $count);
 	}
 
+	/**
+	 * Generates an Item object from an XML tree
+	 *
+	 * @param SimpleXMLElement $xml  root XML element representing the Item
+	 * @return void
+	 */
 	public static function fromXML($xml) {
 		$feats = array();
 		foreach($xml->feat[0] as $k => $v)
 			$feats[(string)$k] = (string)$v;
 
-		return new static((string)$xml->name, +(string)$xml->cost /* convert to number */, (string)$xml->icon, (string)$xml->desc, $feats);
+		return new static((string)$xml->name, +(string)$xml->cost /* convert to number */, (string)$xml->icon, (string)$xml->desc, $feats); // Call constructor
 	}
 }
 
diff --git a/inc/Monster.inc b/inc/Monster.inc
index ae48691..d00532f 100644
--- a/inc/Monster.inc
+++ b/inc/Monster.inc
@@ -1,14 +1,54 @@
 <?php
-
+/**
+ * Represent an Item in the shop or in the Inventory.
+ *
+ * @package inc\Monster.inc
+ * @author     Alexandre Renoux
+ * @author     Pierre-Emmanuel Novac
+ */
 class Monster {
+	/**
+	 * @var string  Name of the Monster.
+	 */
 	public $name = "";
+
+	/**
+	 * @var string  Monster's icon.
+	 */
 	public $icon = "";
-	public $desc = "";
+
+	/**
+	 * @var desc  Monster's description.
+	 */
+	public $desc = ""; // TODO: unused
+
+	/**
+	 * @var int  HP of the Monster.
+	 */
 	public $hp = 1;
+
+	/**
+	 * @var int  Exp given by this monster.
+	 */
 	public $xp = 0;
+
+	/**
+	 * @var int  Monster's level.
+	 */
 	public $level = 1;
 	public $power = 1;
 
+	/**
+	 * Monster's constructor
+	 *
+	 * @param string $name  Monster's name
+	 * @param int $level    Monster's level
+	 * @param int $hp       Monster's HP
+	 * @param int $power       Monster's power
+	 * @param int $xp       Exp given by the Monster
+	 * @param string $icon  Item's icon
+	 * @return void
+	 */
 	function __construct($name, $level, $hp, $xp, $power, $icon) {
 		$this->name = $name;
 		$this->level = $level;
@@ -16,7 +56,6 @@ class Monster {
 		$this->xp = $xp;
 		$this->power = $power;
 		$this->icon = $icon;
-		
 	}
 }
 
diff --git a/inc/account.inc b/inc/account.inc
index 6f398bb..f7e3c05 100644
--- a/inc/account.inc
+++ b/inc/account.inc
@@ -1,6 +1,20 @@
 <?php
+/**
+ * Manages player's account: debit and credit.
+ *
+ * @package inc\account.inc
+ * @author     Alexandre Renoux
+ * @author     Pierre-Emmanuel Novac
+ */
+
 require_once("messages.inc");
 
+/**
+ * Debits the account of a certain amount of gold.
+ *
+ * @param int  $amount amount to debit
+ * @return boolean  true if player had enough gold, false otherwise
+ */
 function debitAccount($amount) {
 	if($_SESSION["mine"]["gold"] < $amount) {
 		sendError("gold_insufficient");
@@ -10,6 +24,12 @@ function debitAccount($amount) {
 	return true;
 }
 
+/**
+ * Credits the account of a certain amount of gold.
+ *
+ * @param int  $amount amount to credit
+ * @return void
+ */
 function creditAccount($amount) {
 	$_SESSION["mine"]["gold"] += $amount;
 }
diff --git a/inc/craftmine.inc b/inc/craftmine.inc
index f5dbbb1..7dd5ba4 100644
--- a/inc/craftmine.inc
+++ b/inc/craftmine.inc
@@ -1,10 +1,23 @@
 <?php
+/**
+ * Sends all data from previous session on page load.
+ *
+ * @package inc\craftmine.inc
+ * @author     Alexandre Renoux
+ * @author     Pierre-Emmanuel Novac
+ */
 
 require_once("mine.inc");
 require_once("shop.inc");
 require_once("dungeon.inc");
 require_once("perso.inc");
 
+/**
+ * Sends all data from previous session on page load.
+ * All data from the different modules are packed in an array.
+ *
+ * @return void
+ */
 function sendCraftMine() {
 	$data = array("gold" => sendMine(),
 		"shop" => sendShop(),
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;
diff --git a/inc/guild.inc b/inc/guild.inc
index c0e8264..f4c10af 100644
--- a/inc/guild.inc
+++ b/inc/guild.inc
@@ -1,8 +1,27 @@
 <?php
+/**
+ * Manages miners guild.
+ *
+ * @package inc\guild.inc
+ * @author     Alexandre Renoux
+ * @author     Pierre-Emmanuel Novac
+ */
 
+/**
+ * Amount of gold required to build the miners guild.
+ */
 define("GUILD_COST",10);
+/**
+ * Amount of gold required to hire a miner.
+ */
 define("MINER_COST",5);
 
+/**
+ * Create the miners guild in the session.
+ * Debits GUILD_COST from the player's gold.
+ *
+ * @return void
+ */
 function createGuild(){
 	if(!empty($_SESSION["guild"])) {
 		sendError("guild_already_built");
@@ -13,6 +32,12 @@ function createGuild(){
 	}
 }
 
+/**
+ * Hire one miner.
+ * Debits MINER_COST from the player's gold.
+ *
+ * @return void
+ */
 function hireMiner(){
 	if(!isset($_SESSION["guild"])){
 		sendError("guild_not_yet_created");
@@ -23,6 +48,11 @@ function hireMiner(){
 	}
 }
 
+/**
+ * Returns the number of miners currently in the guild.
+ *
+ * @return int  number of miners in the guild
+ */
 function sendMiners(){
 	return $_SESSION["mine"]["miners"];
 }
diff --git a/inc/messages.inc b/inc/messages.inc
index 3a7d9b1..8583dc0 100644
--- a/inc/messages.inc
+++ b/inc/messages.inc
@@ -1,5 +1,15 @@
 <?php
+/**
+ * Server to client error/info messages list and helpers.
+ *
+ * @package inc\messages.inc
+ * @author     Alexandre Renoux
+ * @author     Pierre-Emmanuel Novac
+ */
 
+/**
+ * Messages list.
+ */
 $messages = array(
 	"shop_already_built" => "You have already built a shop.",
 	"gold_insufficient" => "You don't have enough gold.",
@@ -18,6 +28,14 @@ $messages = array(
 	"upload_success" => "Save file uploaded successfully: %s",
 );
 
+/**
+ * Sends a message to the client.
+ *
+ * @param string $type  message type, for example "info" or "error"
+ * @param string $msg   message content
+ * @param string $fmt   optional parameters to apply when formating message string
+ * @return void
+ */
 function sendMessage($type, $msg, $fmt = null) {
 	global $messages;
 	$text = $messages[$msg];
@@ -25,10 +43,26 @@ function sendMessage($type, $msg, $fmt = null) {
 	echo json_encode(array($type => $text));
 }
 
+/**
+ * Sends an error message to the client.
+ * Simple wrapper calling sendMessage with "error" as $type.
+ *
+ * @param string $msg   message content
+ * @param string $fmt   optional parameters to apply when formating message string
+ * @return void
+ */
 function sendError($msg, $fmt = null) {
 	sendMessage("error", $msg, $fmt);
 }
 
+/**
+ * Sends an info message to the client.
+ * Simple wrapper calling sendMessage with "info" as $type.
+ *
+ * @param string $msg   message content
+ * @param string $fmt   optional parameters to apply when formating message string
+ * @return void
+ */
 function sendInfo($msg, $fmt = null) {
 	sendMessage("info", $msg, $fmt);
 }
diff --git a/inc/mine.inc b/inc/mine.inc
index 752fc69..d27804a 100644
--- a/inc/mine.inc
+++ b/inc/mine.inc
@@ -1,9 +1,26 @@
 <?php
+/**
+ * Manages the mine.
+ *
+ * @package inc\mine.inc
+ * @author     Alexandre Renoux
+ * @author     Pierre-Emmanuel Novac
+ */
 
+/**
+ * Initializes the gold amount and miners count in the session.
+ *
+ * @return void
+ */
 function initCraftMine() {
 	$_SESSION["mine"] = array("gold" => 0, "miners" => 0);
 }
 
+/**
+ * Transfers all gold from the mine to the player's account.
+ *
+ * @return void
+ */
 function withdrawMine() {
 	$amount = intval($_POST["amount"]);
 	if($amount == 0) return;
@@ -11,6 +28,11 @@ function withdrawMine() {
 	echo json_encode($_SESSION["mine"]["gold"]);
 }
 
+/**
+ * Returns the amount of gold currently owned by the player.
+ *
+ * @return int  amount of gold available
+ */
 function sendMine() {
 	if(empty($_SESSION["mine"])) initCraftMine();
 	$mine = $_SESSION["mine"];
diff --git a/inc/perso.inc b/inc/perso.inc
index 2a514bb..e38fb4c 100644
--- a/inc/perso.inc
+++ b/inc/perso.inc
@@ -1,11 +1,29 @@
 <?php
+/**
+ * Manages player's stats: life, experience, level.
+ *
+ * @package inc\perso.inc
+ * @author     Alexandre Renoux
+ * @author     Pierre-Emmanuel Novac
+ */
 
+/**
+ * Returns all player's stats after initializing them if needed.
+ *
+ * @return int[]  arrays containing player's stats
+ */
 function sendPerso() {
 	if(empty($_SESSION["perso"]))
 		initPerso();
 	return $_SESSION["perso"];
 }
 
+/**
+ * Increases a player's stat.
+ *
+ * @param int  $prop  stat to increase
+ * @return void
+ */
 function increasePerso($prop, $num) {
 	if(empty($_SESSION["perso"]))
 		initPerso();
@@ -69,6 +87,11 @@ function reusable(){
 	}
 }
 
+/**
+ * Copies stats given in POST request to session.
+ *
+ * @return void
+ */
 function updatePerso(){
 	$hp = $_POST["hp"];
 	$maxHP = $_POST["maxHP"];
@@ -84,6 +107,11 @@ function updatePerso(){
 	$_SESSION["perso"]["bonusPower"] = +$bonusPower;
 }
 
+/**
+ * Initializes the player's stats.
+ *
+ * @return void
+ */
 function initPerso(){
 	$_SESSION["perso"]["hp"] = 5;
 	$_SESSION["perso"]["maxHP"] = 5;
diff --git a/inc/savegame.inc b/inc/savegame.inc
index 6d92af2..3e3ffcc 100644
--- a/inc/savegame.inc
+++ b/inc/savegame.inc
@@ -1,11 +1,35 @@
 <?php
+/**
+ * Load and save the game.
+ *
+ * @package inc\savegame.inc
+ * @author     Alexandre Renoux
+ * @author     Pierre-Emmanuel Novac
+ */
 
 require_once("inc/messages.inc");
 require_once("inc/Inventory.inc");
 require_once("inc/Item.inc");
 
+/**
+ * Directory to save to and load from.
+ * The PHP/Apache user must have write permission on this directory.
+ * Use the following commands to give write permissions to the http group:
+ * <samp>
+ * sudo chown :http data/save
+ * sudo chmod g+w data/save
+ * </samp>
+ */
 define("SAVEDIR", "data/save");
 
+/**
+ * Recursively generates an XML tree from an array.
+ * If objects are found, call addToXML() methods which should serialize the object as a child of the XML tree passed as parameter.
+ *
+ * @param array $table  an array with mixed type elements to convert to XML
+ * @param SimpleXMLElement $xml  root XML to add the elements to
+ * @return void
+ */
 function genXML($table, $xml) {
 	foreach($table as $k => $v) {
 		if(is_object($v)) { // Object: either Item or Inventory
@@ -18,22 +42,44 @@ function genXML($table, $xml) {
 	}
 }
 
+/**
+ * Generates the XML save tree from the session.
+ *
+ * @return void
+ */
 function genSave() {
 	$save = new SimpleXMLElement("<save/>");
 	genXML($_SESSION, $save);
 	return $save;
 }
 
+/**
+ * Generates the save file name using current date/time.
+ * The date function will use the server's timezone which could be inconsistent with the client timezone.
+ * 
+ * @return string  the generated file name
+ */
 function genFilename() {
 	return "craftmine-".date("d-m-Y_H-i-s").".save.xml";
 }
 
+/**
+ * Save the XML save tree as an XML file named after the results of genFilename in SAVEDIR.
+ * Fails and send an error the the client if permissions are incorrectly set. Watch for errors in PHP log.
+ *
+ * @return void
+ */
 function saveGame() {
 	$save = genSave();
 	if($save->asXML(SAVEDIR."/".genFilename())) sendInfo("gamesave_ok");
 	else sendError("gamesave_error");
 }
 
+/**
+ * Sends the current game or a specific save file given by the filename GET parameter to the client.
+ *
+ * @return void
+ */
 function downSave() {
 	$save = "";
 	$filename = "";
@@ -53,11 +99,24 @@ function downSave() {
 	echo $save;
 }
 
+/**
+ * Sends the list of available saves to the client.
+ * Warning: this function changes directory.
+ *
+ * @return void
+ */
 function listSaves() {
 	chdir(SAVEDIR); // Go to SAVEDIR folder, avoiding leading folder name in file list
 	echo json_encode(glob("*.save.xml"));
 }
 
+/**
+ * Reads an XML tree and deserializes it to an array.
+ *
+ * @param SimpleXMLElement $xml  root XML to read the elements from
+ * @param array $table  an empty array to stores the elements to, passed by reference
+ * @return void
+ */
 function parseSave($xml, &$table) { // Passing $table by reference
 	foreach($xml as $k => $v) {
 		if($v->count() == 0) { // No child, treat as string
@@ -76,6 +135,11 @@ function parseSave($xml, &$table) { // Passing $table by reference
 	}
 }
 
+/**
+ * Deletes a save file given as the filename POST parameter.
+ *
+ * @return void
+ */
 function deleteSave() {
 	if(empty($_POST["filename"])) return;
 	$path = SAVEDIR . "/" . basename($_POST["filename"]); // remove any leading directory
@@ -84,6 +148,12 @@ function deleteSave() {
 	else sendError("gamesave_delete_fail");
 }
 
+/**
+ * Loads a save file given as the filename POST parameter to the session.
+ * Empties the session beforehand.
+ *
+ * @return void
+ */
 function loadSave() {
 	if(empty($_POST["filename"])) return;
 	$xml = simplexml_load_file(SAVEDIR . "/" . $_POST["filename"]);
@@ -95,6 +165,14 @@ function loadSave() {
 	parseSave($xml, $_SESSION);
 }
 
+/**
+ * Reads a save file sent by the client.
+ * Parse the received file then generate it again to clean it for any unwanted 
+ * and make sure that it is a valid XML save file.
+ * XML errors are simply ignored and an error is sent to the client if something wrong happens.
+ *
+ * @return void
+ */
 function uploadSave() {
 	$fname = basename($_FILES['savefile']['name']);
 	$src = $_FILES['savefile']['tmp_name'];
diff --git a/inc/shop.inc b/inc/shop.inc
index 69161e1..2dbd19d 100644
--- a/inc/shop.inc
+++ b/inc/shop.inc
@@ -1,4 +1,11 @@
 <?php
+/**
+ * Manages the shop.
+ *
+ * @package inc\shop.inc
+ * @author     Alexandre Renoux
+ * @author     Pierre-Emmanuel Novac
+ */
 
 require_once("messages.inc");
 require_once("account.inc");
@@ -6,19 +13,24 @@ require_once("Item.inc");
 require_once("Inventory.inc");
 require_once("perso.inc");
 
+/**
+ * Loads all the shop's items from the XML file data/items.xml.
+ *
+ * @return array  contains all the Item objects
+ */
 function loadShop(){
-	$items = simplexml_load_file('data/items.xml');
-	$shop = array("cost"=>(string)$items["cost"],"items"=>array());
-	foreach($items as $cat){
+	$items = simplexml_load_file('data/items.xml'); //TODO: handle errors
+	$shop = array("cost"=>(string)$items["cost"],"items"=>array()); //TODO: cost is a string?
+	foreach($items as $cat){ // Loop over all categories
 		$category = (string)$cat["name"];
 		$shop["items"][$category] = array();
-		foreach($cat as $item){
+		foreach($cat as $item){ // Loop over all items inside a category
 			$feats = array();
-			foreach($item->features[0] as $k => $v)
+			foreach($item->features[0] as $k => $v) // Reads features
 				$feats[(string)$k] = (string)$v;
 			$shop["items"][$category][] = new Item(
 				(string)$item->name,
-				intval($item->cost),
+				intval($item->cost), //Note: cost is an int here.
 				(string)$item->icon,
 				(string)$item->description,
 				$feats);
@@ -27,6 +39,12 @@ function loadShop(){
 	return $shop;
 }
 
+/**
+ * Gets an Item object from the shop from its name.
+ *
+ * @params string $name  the name of the object to search for
+ * @return Item|false  the Item object or false if the item was not found
+ */
 function getItem($name) {
 	$shop=loadShop();
 	foreach($shop["items"] as $cat) {
@@ -40,16 +58,32 @@ function getItem($name) {
 	return false;
 }
 
+/**
+ * Marks the shop as created in the session.
+ *
+ * @return void
+ */
 function initShop() {
 	$_SESSION["shop"] = true;
 }
 
+/**
+ * Returns the shop array if it was created.
+ *
+ * @return array  shop array as created by loadShop
+ */
 function sendShop() {
 	if(!empty($_SESSION["shop"]))
 		return loadShop();
 	else return false;
 }
 
+/**
+ * Creates the shop in the session and sends it to the client.
+ * Debits the shop's cost from the player's gold.
+ *
+ * @return void
+ */
 function buildShop() {
 	$shop=loadShop();
 	if(!empty($_SESSION["shop"])) {
@@ -61,14 +95,24 @@ function buildShop() {
 	}
 }
 
+/**
+ * Debits the item's cost specified as the item POST parameter, adds it to the Inventory and sends it to the client.
+ *
+ * @return void
+ */
 function buyItem() {
 	$item = getItem($_POST["item"]);
 	if($item && debitAccount($item->cost)) {
-		$tab = Inventory::addItem($item);   
-		echo json_encode($tab); //renvoyer un tableau avec comme première entrée $item et comme deuxième entrée le nombre 
+		$tab = Inventory::addItem($item);
+		echo json_encode($tab); // Sends an array with the Item as first member and count as second.
 	}
 }
 
+/**
+ * Invoke useItem on an item passed as the item POST parameter, sends to the client the updated player stats and the item.
+ *
+ * @return void
+ */
 function useItem(){
 	$item = getItem($_POST["item"]);
 	$it = Inventory::useItem($item);