From d055a15f29f06cdd1053de01fafa78f25f90d42b Mon Sep 17 00:00:00 2001
From: Quitta <none@none>
Date: Tue, 10 Sep 2013 21:26:03 +0200
Subject: [PATCH] added documentation for assigned, dblayer and forwarded class

--HG--
branch : quitta-gsoc-2013
---
 .hgignore                                     | 10 +-
 .../ryzom_ams/ams_lib/autoload/assigned.php   | 96 ++++++++++++++++---
 .../ryzom_ams/ams_lib/autoload/dblayer.php    | 30 +++++-
 .../ryzom_ams/ams_lib/autoload/forwarded.php  | 79 +++++++++++++--
 4 files changed, 189 insertions(+), 26 deletions(-)

diff --git a/.hgignore b/.hgignore
index 5b6bebb35..f0a8e0993 100644
--- a/.hgignore
+++ b/.hgignore
@@ -200,7 +200,15 @@ code/ryzom/common/data_leveldesign/leveldesign/game_element/xp_table/skills.skil
 code/ryzom/common/data_leveldesign/leveldesign/game_element/xp_table/xptable.xp_table
 code/ryzom/tools/server/sql/ryzom_admin_default_data.sql
 code/ryzom/tools/server/ryzom_ams/drupal
-code/ryzom/tools/server/ryzom_ams/drupal_module/ryzommanage/ams_lib
+code/ryzom/tools/server/ryzom_ams/drupal_module/ryzommanage/ams_lib/autoload
+code/ryzom/tools/server/ryzom_ams/drupal_module/ryzommanage/ams_lib/configs
+code/ryzom/tools/server/ryzom_ams/drupal_module/ryzommanage/ams_lib/cron
+code/ryzom/tools/server/ryzom_ams/drupal_module/ryzommanage/ams_lib/img
+code/ryzom/tools/server/ryzom_ams/drupal_module/ryzommanage/ams_lib/plugins
+code/ryzom/tools/server/ryzom_ams/drupal_module/ryzommanage/ams_lib/smarty
+code/ryzom/tools/server/ryzom_ams/drupal_module/ryzommanage/ams_lib/translations
+code/ryzom/tools/server/ryzom_ams/drupal_module/ryzommanage/ams_lib/libinclude.php
+
 # Linux server compile
 code/ryzom/server/src/entities_game_service/entities_game_service
 code/ryzom/server/src/frontend_service/frontend_service
diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/assigned.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/assigned.php
index 6d2a558c3..4989767aa 100644
--- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/assigned.php
+++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/assigned.php
@@ -1,13 +1,25 @@
 <?php
-
+/**
+* Handles the assigning of a ticket to a user. This is being used to make someone responsible for the handling and solving of a ticket.
+* The idea is that someone can easily assign a ticket to himself and by doing that, he makes aware to the other moderators that he will deal with the ticket in the future.
+* @author Daan Janssens, mentored by Matthew Lagoe
+* 
+*/
 class Assigned{
+
+    private $user; /**< The id of the user being assigned */ 
+    private $ticket; /**< The id of the ticket being assigned */ 
     
-    private $user;
-    private $ticket;
     
     ////////////////////////////////////////////Functions////////////////////////////////////////////////////
-  
-    //Assigns a ticket to a user or returns error message
+    
+    /**
+    * Assigns a ticket to a user or returns an error message.
+    * It will first check if the ticket isn't already assigned, if not, it will create a new 'assigned' entry.
+    * @param $user_id the id of the user we want to assign to the ticket
+    * @param $ticket_id the id of the ticket.
+    * @return A string, if assigning succeedded "SUCCESS_ASSIGNED" will be returned, else "ALREADY_ASSIGNED" will be returned.
+    */
     public static function assignTicket( $user_id, $ticket_id) {
         $dbl = new DBLayer("lib");
         //check if ticket is already assigned, if so return "ALREADY ASSIGNED"
@@ -22,7 +34,14 @@ class Assigned{
       
     }
     
-    //Unsign a ticket to a user or returns error message
+    
+    /**
+    * Unassign a ticket being coupled to a user or return an error message.
+    * It will first check if the ticket is assigned, if this is indeed the case it will delete the 'assigned' entry.
+    * @param $user_id the id of the user we want to unassign from the ticket
+    * @param $ticket_id the id of the ticket.
+    * @return A string, if unassigning succeedded "SUCCESS_UNASSIGNED" will be returned, else "NOT_ASSIGNED" will be returned.
+    */
     public static function unAssignTicket( $user_id, $ticket_id) {
         $dbl = new DBLayer("lib");
         //check if ticket is really assigned to that user
@@ -37,7 +56,11 @@ class Assigned{
       
     }
     
-    // Get the id of the user assigned to a ticket
+    /**
+    * Get the (external) id of the user assigned to a ticket
+    * @param $ticket_id the Id of the ticket that's being queried
+    * @return The (external)id of the user being assigned to the ticket
+    */
     public static function getUserAssignedToTicket($ticket_id) {
         $dbl = new DBLayer("lib");
         $statement = $dbl->execute("SELECT ticket_user.ExternId FROM `assigned` JOIN `ticket_user` ON assigned.User = ticket_user.TUserId WHERE `Ticket` = :ticket_id", Array('ticket_id' => $ticket_id));
@@ -48,6 +71,12 @@ class Assigned{
       
     }
     
+    /**
+    * Check if a ticket is already assigned (in case the user_id param is used, it will check if it's assigned to that user)
+    * @param $ticket_id the Id of the ticket that's being queried
+    * @param $user_id the id of the user, default parameter = 0, by using a user_id, it will check if that user is assigned to the ticket.
+    * @return true in case it's assigned, false in case it isn't.
+    */
     public static function isAssigned( $ticket_id, $user_id = 0) {
         $dbl = new DBLayer("lib");
         //check if ticket is already assigned
@@ -62,16 +91,30 @@ class Assigned{
     }
     
     ////////////////////////////////////////////Methods////////////////////////////////////////////////////
-     
+    
+    
+    /**
+    * A constructor.
+    * Empty constructor
+    */
     public function __construct() {
     }
     
-    //set values
+    
+    /**
+    * sets the object's attributes.
+    * @param $values should be an array of the form array('User' => user_id, 'Ticket' => ticket_id).
+    */
     public function set($values) {
         $this->setUser($values['User']);
         $this->setTicket($values['Ticket']);
     }
     
+    
+    /**
+    * creates a new 'assigned' entry.
+    * this method will use the object's attributes for creating a new 'assigned' entry in the database.
+    */
     public function create() {
         $dbl = new DBLayer("lib");
         $query = "INSERT INTO `assigned` (`User`,`Ticket`) VALUES (:user, :ticket)";
@@ -79,7 +122,11 @@ class Assigned{
         $dbl->execute($query, $values);
     }
     
-    //delete entry
+    
+    /**
+    * deletes an existing 'assigned' entry.
+    * this method will use the object's attributes for deleting an existing 'assigned' entry in the database.
+    */
     public function delete() {
         $dbl = new DBLayer("lib");
         $query = "DELETE FROM `assigned` WHERE `User` = :user_id and `Ticket` = :ticket_id";
@@ -87,10 +134,14 @@ class Assigned{
         $dbl->execute($query, $values);
     }
 
-    //Load with sGroupId
-    public function load( $user_id, $user_id) {
+    /**
+    * loads the object's attributes.
+    * loads the object's attributes by giving a ticket_id, it will put the matching user_id and the ticket_id into the attributes.
+    * @param $ticket_id the id of the ticket that should be loaded
+    */
+    public function load($ticket_id) {
         $dbl = new DBLayer("lib");
-        $statement = $dbl->execute("SELECT * FROM `assigned` WHERE `Ticket` = :ticket_id AND `User` = :user_id", Array('ticket_id' => $ticket_id, 'user_id' => $user_id));
+        $statement = $dbl->execute("SELECT * FROM `assigned` WHERE `Ticket` = :ticket_id", Array('ticket_id' => $ticket_id));
         $row = $statement->fetch();
         $this->set($row);
     }
@@ -98,22 +149,37 @@ class Assigned{
 
     ////////////////////////////////////////////Getters////////////////////////////////////////////////////
     
+    /**
+    * get user attribute of the object.
+    */
     public function getUser(){
         return $this->user;
     }
     
+    
+    /**
+    * get ticket attribute of the object.
+    */
     public function getTicket(){
         return $this->ticket;
     }
     
     ////////////////////////////////////////////Setters////////////////////////////////////////////////////
 
+    /**
+    * set user attribute of the object.
+    * @param $u integer id of the user
+    */
     public function setUser($u){
         $this->user = $u;
     }
     
-    public function setTicket($g){
-        $this->ticket = $g;
+    /**
+    * set ticket attribute of the object.
+    * @param $t integer id of the ticket
+    */
+    public function setTicket($t){
+        $this->ticket = $t;
     }
    
     
diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/dblayer.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/dblayer.php
index c5b7375c3..534eea1b9 100644
--- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/dblayer.php
+++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/dblayer.php
@@ -1,8 +1,19 @@
 <?php
+/**
+* Handles the database connections. It uses PDO to connect to the different databases. It will use the argument of the constructor to setup a connection to the database 
+* with the matching entry in the $cfg global variable.
+* @author Daan Janssens, mentored by Matthew Lagoe
+* 
+*/
 class DBLayer{
     
-    private $PDO;
+    private $PDO; /**< The PDO object, instantiated by the constructor */ 
     
+    /**
+    * The constructor.
+    * Instantiates the PDO object attribute by connecting to the arguments matching database(the db info is stored in the $cfg global var)
+    * @param String, the name of the databases entry in the $cfg global var.
+    */
     function __construct($db)
     {
         global $cfg;
@@ -19,18 +30,35 @@ class DBLayer{
 
     }
     
+    /**
+    * execute a query that doesn't have any parameters
+    * @param $query the mysql query
+    * @return returns a PDOStatement object 
+    */
     public function executeWithoutParams($query){
         $statement = $this->PDO->prepare($query);
         $statement->execute();
         return $statement;
     }
     
+    /**
+    * execute a query that has parameters
+    * @param $query the mysql query
+    * @param $params the parameters that are being used by the query
+    * @return returns a PDOStatement object 
+    */
     public function execute($query,$params){
         $statement = $this->PDO->prepare($query);
         $statement->execute($params);
         return $statement;
     }
     
+    /**
+    * execute a query (an insertion query) that has parameters and return the id of it's insertion
+    * @param $query the mysql query
+    * @param $params the parameters that are being used by the query
+    * @return returns the id of the last inserted element.
+    */
     public function executeReturnId($query,$params){
         $statement = $this->PDO->prepare($query);
         $this->PDO->beginTransaction();
diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/forwarded.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/forwarded.php
index 003811fe9..54fece58c 100644
--- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/forwarded.php
+++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/forwarded.php
@@ -1,13 +1,26 @@
 <?php
-
+/**
+* Handles the forwarding of a ticket to a support_group. This is being used to transfer tickets to different groups (eg Developers, Website-Team, SupportGroup etc..)
+* The idea is that someone can easily forward a ticket to a group and by doing that, the moderators that are in that group will receive the ticket in their todo queue.
+* @author Daan Janssens, mentored by Matthew Lagoe
+* 
+*/
 class Forwarded{
     
-    private $group;
-    private $ticket;
+    private $group; /**< The id of the group to which the ticket is being forwarded */ 
+    private $ticket; /**< The id of the ticket being forwarded */ 
     
     ////////////////////////////////////////////Functions////////////////////////////////////////////////////
-  
-    //AForward a ticket to a group, also removes the previous group where it was assigned to.
+    
+    
+    /**
+    * Forward a ticket to a group, also removes the previous group where it was forwarded to.
+    * It will first check if the ticket is already forwarded, if that's the case, it will delete that entry.
+    * Afterwards it creates the new forward entry
+    * @param $group_id the id of the support group we want to forward the ticket to.
+    * @param $ticket_id the id of the ticket.
+    * @return A string, if assigning succeedded "SUCCESS_FORWARDED" will be returned.
+    */
     public static function forwardTicket( $group_id, $ticket_id) {
         $dbl = new DBLayer("lib");
         if (forwarded::isForwarded($ticket_id)){
@@ -22,6 +35,12 @@ class Forwarded{
       
     }
     
+    
+    /**
+    * get the id of the group a ticket is forwarded to.
+    * @param $ticket_id the id of the ticket.
+    * @return the id of the group
+    */
     public static function getSGroupOfTicket($ticket_id) {
         $forw = new self();
         $forw->load($ticket_id);
@@ -29,6 +48,11 @@ class Forwarded{
     }
     
     
+    /**
+    * check if the ticket is forwarded
+    * @param $ticket_id the id of the ticket.
+    * @return returns true if the ticket is forwarded, else return false;
+    */
     public static function isForwarded( $ticket_id) {
         $dbl = new DBLayer("lib");
         if( $dbl->execute(" SELECT * FROM `forwarded` WHERE `Ticket` = :ticket_id", array('ticket_id' => $ticket_id))->rowCount()){
@@ -41,15 +65,29 @@ class Forwarded{
     
     ////////////////////////////////////////////Methods////////////////////////////////////////////////////
      
+     
+    /**
+    * A constructor.
+    * Empty constructor
+    */
     public function __construct() {
     }
     
-    //set values
+   
+    /**
+    * sets the object's attributes.
+    * @param $values should be an array of the form array('Group' => group_id, 'Ticket' => ticket_id).
+    */
     public function set($values) {
         $this->setGroup($values['Group']);
         $this->setTicket($values['Ticket']);
     }
     
+    
+    /**
+    * creates a new 'forwarded' entry.
+    * this method will use the object's attributes for creating a new 'forwarded' entry in the database.
+    */
     public function create() {
         $dbl = new DBLayer("lib");
         $query = "INSERT INTO `forwarded` (`Group`,`Ticket`) VALUES (:group, :ticket)";
@@ -57,7 +95,11 @@ class Forwarded{
         $dbl->execute($query, $values);
     }
     
-    //delete entry
+    
+    /**
+    * deletes an existing 'forwarded' entry.
+    * this method will use the object's attributes for deleting an existing 'forwarded' entry in the database.
+    */
     public function delete() {
         $dbl = new DBLayer("lib");
         $query = "DELETE FROM `forwarded` WHERE `Group` = :group_id and `Ticket` = :ticket_id";
@@ -65,7 +107,12 @@ class Forwarded{
         $dbl->execute($query, $values);
     }
 
-    //Load with sGroupId
+
+    /**
+    * loads the object's attributes.
+    * loads the object's attributes by giving a ticket_id, it will put the matching group_id and the ticket_id into the attributes.
+    * @param $ticket_id the id of the ticket that should be loaded
+    */
     public function load( $ticket_id) {
         $dbl = new DBLayer("lib");
         $statement = $dbl->execute("SELECT * FROM `forwarded` WHERE `Ticket` = :ticket_id", Array('ticket_id' => $ticket_id));
@@ -75,21 +122,35 @@ class Forwarded{
     
 
     ////////////////////////////////////////////Getters////////////////////////////////////////////////////
-    
+     
+    /**
+    * get group attribute of the object.
+    */
     public function getGroup(){
         return $this->group;
     }
     
+    /**
+    * get ticket attribute of the object.
+    */
     public function getTicket(){
         return $this->ticket;
     }
     
     ////////////////////////////////////////////Setters////////////////////////////////////////////////////
 
+    /**
+    * set group attribute of the object.
+    * @param $g integer id of the group
+    */
     public function setGroup($g){
         $this->group = $g;
     }
     
+    /**
+    * set ticket attribute of the object.
+    * @param $t integer id of the ticket
+    */
     public function setTicket($t){
         $this->ticket = $t;
     }