From faefddcb8b3d3ac491331b702f8a8ac6fe58a894 Mon Sep 17 00:00:00 2001
From: piernov <piernov@piernov.org>
Date: Sun, 8 May 2016 20:14:40 +0200
Subject: First PHPDoc push, Inventory not complete

---
 inc/Inventory.inc | 39 ++++++++++++++++++++++++++--
 inc/Item.inc      | 58 +++++++++++++++++++++++++++++++++++++++--
 inc/Monster.inc   | 44 ++++++++++++++++++++++++++++---
 inc/account.inc   | 19 ++++++++++++++
 inc/craftmine.inc | 12 +++++++++
 inc/dungeon.inc   | 50 +++++++++++++++++++++++++++++++++---
 inc/guild.inc     | 29 +++++++++++++++++++++
 inc/messages.inc  | 33 ++++++++++++++++++++++++
 inc/mine.inc      | 21 +++++++++++++++
 inc/perso.inc     | 27 +++++++++++++++++++
 inc/savegame.inc  | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 inc/shop.inc      | 59 ++++++++++++++++++++++++++++++++++++------
 12 files changed, 449 insertions(+), 19 deletions(-)

diff --git a/inc/Inventory.inc b/inc/Inventory.inc
index 2be48f8..dd65ee5 100644
--- a/inc/Inventory.inc
+++ b/inc/Inventory.inc
@@ -1,17 +1,40 @@
 <?php
-
+/**
+ * Represent the player's Inventory.
+ * Implemented as a singleton in the session.
+ *
+ * @author     Alexandre Renoux
+ * @author     Pierre-Emmanuel Novac
+ */
 class Inventory {
-
+        /**
+         * Arrays of array with Item and Item's count
+         */
 	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();
@@ -19,6 +42,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){
@@ -31,6 +60,12 @@ 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);
diff --git a/inc/Item.inc b/inc/Item.inc
index 8eebbf8..4ec984f 100644
--- a/inc/Item.inc
+++ b/inc/Item.inc
@@ -2,13 +2,49 @@
 
 require_once("perso.inc");
 
+/**
+ * Represent an Item in the shop or in the Inventory.
+ *
+ * @author     Alexandre Renoux
+ * @author     Pierre-Emmanuel Novac
+ */
 class Item {
+
+	/**
+	 * Name of the item.
+	 */
 	public $name = "";
+
+	/**
+	 * Item's cost.
+	 */
 	public $cost = 0;
+
+	/**
+	 * Item's icon.
+	 */
 	public $icon = "";
+
+	/**
+	 * Item's description.
+	 */
 	public $desc = "";
+
+	/**
+	 * 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,15 +53,27 @@ class Item {
 		$this->feat = $feat;
 	}
 
+	/**
+	 * Applies Item's features on the player.
+	 *
+	 * @return void
+	 */
 	function consume() {
 		foreach($this->feat as $k => $v) {
 			switch($k) {
 				case "hp": increasePerso("hp", +$v); break;
-				case "power": break;
+				case "power": break; // TODO: do something with power
 			}
 		}
 	}
 
+	/**
+	 * 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 +86,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 c7063ec..4450b59 100644
--- a/inc/Monster.inc
+++ b/inc/Monster.inc
@@ -1,20 +1,58 @@
 <?php
-
+/**
+ * Represent an Item in the shop or in the Inventory.
+ *
+ * @author     Alexandre Renoux
+ * @author     Pierre-Emmanuel Novac
+ */
 class Monster {
+	/**
+	 * Name of the Monster.
+	 */
 	public $name = "";
+
+	/**
+	 * Monster's icon.
+	 */
 	public $icon = "";
-	public $desc = "";
+
+	/**
+	 * Monster's description.
+	 */
+	public $desc = ""; // TODO: unused
+
+	/**
+	 * HP of the Monster.
+	 */
 	public $hp = 1;
+
+	/**
+	 *  Exp given by this monster.
+	 */
 	public $xp = 0;
+
+	/**
+	 * Monster's level.
+	 */
 	public $level = 1;
 
+
+	/**
+	 * Monster's constructor
+	 *
+	 * @param string $name  Monster's name
+	 * @param int $level    Monster's level
+	 * @param int $hp       Monster's HP
+	 * @param int $xp       Exp given by the Monster
+	 * @param string $icon  Item's icon
+	 * @return void
+	 */
 	function __construct($name, $level, $hp, $xp, $icon) {
 		$this->name = $name;
 		$this->level = $level;
 		$this->hp = $hp;
 		$this->xp = $xp;
 		$this->icon = $icon;
-		
 	}
 }
 
diff --git a/inc/account.inc b/inc/account.inc
index 6f398bb..bfbd47b 100644
--- a/inc/account.inc
+++ b/inc/account.inc
@@ -1,6 +1,19 @@
 <?php
+/**
+ * Manages player's account: debit and credit.
+ *
+ * @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 +23,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..e72db34 100644
--- a/inc/craftmine.inc
+++ b/inc/craftmine.inc
@@ -1,10 +1,22 @@
 <?php
+/**
+ * Sends all data from previous session on page load.
+ *
+ * @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 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;
diff --git a/inc/guild.inc b/inc/guild.inc
index c0e8264..f348348 100644
--- a/inc/guild.inc
+++ b/inc/guild.inc
@@ -1,8 +1,26 @@
 <?php
+/**
+ * Manages miners guild.
+ *
+ * @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 +31,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 +47,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..50bbafb 100644
--- a/inc/messages.inc
+++ b/inc/messages.inc
@@ -1,5 +1,14 @@
 <?php
+/**
+ * Server to client error/info messages list and helpers.
+ *
+ * @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 +27,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 +42,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..38dc717 100644
--- a/inc/mine.inc
+++ b/inc/mine.inc
@@ -1,9 +1,25 @@
 <?php
+/**
+ * Manages the mine.
+ *
+ * @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 +27,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 f455173..c81b72b 100644
--- a/inc/perso.inc
+++ b/inc/perso.inc
@@ -1,17 +1,39 @@
 <?php
+/**
+ * Manages player's stats: life, experience, level.
+ *
+ * @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();
 	$_SESSION["perso"][$prop] += $num;
 }
 
+/**
+ * Copies stats given in POST request to session.
+ *
+ * @return void
+ */
 function updatePerso(){
 	$hp = $_POST["hp"];
 	$xp = $_POST["xp"];
@@ -21,6 +43,11 @@ function updatePerso(){
 	$_SESSION["perso"]["lv"] = +$lv;
 }
 
+/**
+ * Initializes the player's stats.
+ *
+ * @return void
+ */
 function initPerso(){
 	$_SESSION["perso"]["hp"] = 5;
 	$_SESSION["perso"]["xp"] = 0;
diff --git a/inc/savegame.inc b/inc/savegame.inc
index 6d92af2..3c5613b 100644
--- a/inc/savegame.inc
+++ b/inc/savegame.inc
@@ -1,11 +1,34 @@
 <?php
+/**
+ * Load and save the game.
+ *
+ * @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 +41,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 +98,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 +134,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 +147,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 +164,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..79c6776 100644
--- a/inc/shop.inc
+++ b/inc/shop.inc
@@ -1,4 +1,10 @@
 <?php
+/**
+ * Manages the shop.
+ *
+ * @author     Alexandre Renoux
+ * @author     Pierre-Emmanuel Novac
+ */
 
 require_once("messages.inc");
 require_once("account.inc");
@@ -6,19 +12,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 +38,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 +57,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 +94,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);
-- 
cgit v1.2.3-70-g09d2