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/savegame.inc | 77 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

(limited to 'inc/savegame.inc')

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'];
-- 
cgit v1.2.3-54-g00ecf