Merge branch 'phpdoc' into piernov

1 files changed, 52 insertions, 8 deletions

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);