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/shop.inc | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 51 insertions(+), 8 deletions(-)

(limited to 'inc/shop.inc')

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-54-g00ecf