From c22a206a0e9e79f0e856937891c2692c1e43bebd Mon Sep 17 00:00:00 2001
From: Keir <keir@nellyer.co.uk>
Date: Tue, 8 Dec 2015 10:38:44 +0000
Subject: [PATCH] Added some documentation (mainly declaring variable types).

---
 .../Mineplex.ChatSnapManager/web/report.php   | 123 ++++++++++++++++--
 1 file changed, 112 insertions(+), 11 deletions(-)

diff --git a/Plugins/Mineplex.ChatSnapManager/web/report.php b/Plugins/Mineplex.ChatSnapManager/web/report.php
index e0da4ec0f..92b80945d 100644
--- a/Plugins/Mineplex.ChatSnapManager/web/report.php
+++ b/Plugins/Mineplex.ChatSnapManager/web/report.php
@@ -9,6 +9,7 @@ if (!isset($_GET["id"]) || empty($_GET["id"])) {
 }
 
 $id = $_GET["id"];
+// TODO: prevent escaping to other directories
 $filePath = $dataDir . $id . ".json";
 
 if (file_exists($filePath)) {
@@ -17,6 +18,9 @@ if (file_exists($filePath)) {
     echo "Invalid identifier.";
 }
 
+/**
+ * @param array $dataArray root JSON data array.
+ */
 function displayMessages($dataArray)
 {
     $snapshot = toSnapshot($dataArray);
@@ -27,36 +31,58 @@ function displayMessages($dataArray)
     }
 }
 
+/**
+ * @param String $filename
+ * @return array JSON data array.
+ */
 function toDataArray($filename)
 {
     return json_decode(file_get_contents($filename), true);
 }
 
+/**
+ * @param Message $message
+ * @return string
+ */
 function getMessageLine($message)
 {
     return $message->getSender()->getUsername() . " - " . $message->getMessage();
 }
 
-function toSnapshot($dataArray)
+/**
+ * @param array $snapshotData Snapshot data array.
+ * @return Snapshot
+ */
+function toSnapshot($snapshotData)
 {
-    $identifier = $dataArray["token"];
-    $players = getPlayers($dataArray["usernames"]);
-    $messages = getMessages($players, $dataArray["snapshots"]);
+    $identifier = $snapshotData["token"];
+    $players = getPlayers($snapshotData["usernames"]);
+    $messages = getMessages($players, $snapshotData["snapshots"]);
     return new Snapshot($identifier, $messages, $players);
 }
 
-function getMessages($snapshot, $messagesArray)
+/**
+ * @param Player[] $players
+ * @param array $messagesData Messages data array.
+ * @return Message[]
+ */
+function getMessages($players, $messagesData)
 {
     $messages = array();
 
-    for ($i = 0; $i < count($messagesArray); $i++)
+    for ($i = 0; $i < count($messagesData); $i++)
     {
-        $messages[$i] = getMessage($snapshot, $messagesArray[$i]);
+        $messages[$i] = getMessage($players, $messagesData[$i]);
     }
 
     return $messages;
 }
 
+/**
+ * @param Player[] $players
+ * @param array $messageData Message data array.
+ * @return Message
+ */
 function getMessage($players, $messageData)
 {
     $sender = getPlayer($players, $messageData["sender"]);
@@ -67,6 +93,11 @@ function getMessage($players, $messageData)
     return new Message($sender, $recipients, $timestamp, $message);
 }
 
+/**
+ * @param Player[] $players
+ * @param String[] $uuidArray the UUIDs of the players to fetch
+ * @return Player[]
+ */
 function getPlayersFromUUIDs($players, $uuidArray)
 {
     $matchedPlayers = array();
@@ -79,7 +110,11 @@ function getPlayersFromUUIDs($players, $uuidArray)
     return $matchedPlayers;
 }
 
-function getPlayers($playersArray)
+/**
+ * @param Player[] $playersArray
+ * @return Player[]
+ */
+function getPlayers($playersArray) // String UUID as Key
 {
     $players = array();
 
@@ -91,6 +126,11 @@ function getPlayers($playersArray)
     return $players;
 }
 
+/**
+ * @param Player[] $players
+ * @param String $uuid
+ * @return Player
+ */
 function getPlayer($players, $uuid)
 {
     $player = $players[$uuid];
@@ -106,10 +146,22 @@ function getPlayer($players, $uuid)
 }
 
 class Snapshot {
-    private $identifier;
-    private $messages;
-    private $players;
 
+    /** @var String */
+    private $identifier;
+
+    /** @var Message[] */
+    private $messages;
+
+    /** @var Player[] */
+    private $players; // String UUID as Key
+
+    /**
+     * Snapshot constructor.
+     * @param String $identifier
+     * @param Message[] $messages
+     * @param Player[] $players
+     */
     function Snapshot($identifier, $messages, $players)
     {
         $this->identifier = $identifier;
@@ -117,16 +169,25 @@ class Snapshot {
         $this->players = $players;
     }
 
+    /**
+     * @return String
+     */
     public function getIdentifier()
     {
         return $this->identifier;
     }
 
+    /**
+     * @return Message[]
+     */
     public function getMessages()
     {
         return $this->messages;
     }
 
+    /**
+     * @return Player[]
+     */
     public function getPlayers()
     {
         return $this->players;
@@ -135,11 +196,25 @@ class Snapshot {
 
 class Message
 {
+    /** @var Player */
     private $sender;
+
+    /** @var Player[] */
     private $recipients;
+
+    /** @var Int */
     private $timestamp;
+
+    /** @var String */
     private $message;
 
+    /**
+     * Message constructor.
+     * @param Player $sender
+     * @param Player[] $recipients
+     * @param Int $timestamp
+     * @param String $message
+     */
     function Message($sender, $recipients, $timestamp, $message)
     {
         $this->sender = $sender;
@@ -148,21 +223,33 @@ class Message
         $this->message = $message;
     }
 
+    /**
+     * @return Player
+     */
     public function getSender()
     {
         return $this->sender;
     }
 
+    /**
+     * @return Player[]
+     */
     public function getRecipients()
     {
         return $this->recipients;
     }
 
+    /**
+     * @return Int
+     */
     public function getTimestamp()
     {
         return $this->timestamp;
     }
 
+    /**
+     * @return String
+     */
     public function getMessage()
     {
         return $this->message;
@@ -171,20 +258,34 @@ class Message
 
 class Player
 {
+    /** @var String */
     private $uuid;
+
+    /** @var String */
     private $username;
 
+    /**
+     * Player constructor.
+     * @param String $uuid
+     * @param String $username
+     */
     function Player($uuid, $username)
     {
         $this->uuid = $uuid;
         $this->username = $username;
     }
 
+    /**
+     * @return String
+     */
     public function getUUID()
     {
         return $this->uuid;
     }
 
+    /**
+     * @return String
+     */
     public function getUsername()
     {
         return $this->username;