From 4e20ab5b91de9c68d531367217aa28f7dc865c64 Mon Sep 17 00:00:00 2001
From: Quitta <Quitta@localhost>
Date: Thu, 12 Sep 2013 19:28:56 +0200
Subject: [PATCH] the lib is entirely documented, still webusers and func/inc
 folders to go :D

---
 .../ams_lib/autoload/ticket_queue.php         |  58 +++++++-
 .../ams_lib/autoload/ticket_queue_handler.php |  49 ++++++-
 .../ams_lib/autoload/ticket_reply.php         | 121 ++++++++++++++---
 .../ams_lib/autoload/ticket_user.php          | 124 ++++++++++++++++--
 .../ryzom_ams/ams_lib/autoload/users.php      | 110 ++++++++++------
 5 files changed, 376 insertions(+), 86 deletions(-)

diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_queue.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_queue.php
index ef0b15bd2..2d6752057 100644
--- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_queue.php
+++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_queue.php
@@ -1,35 +1,56 @@
 <?php
+/**
+* Data class that holds a lot of queries that load specific tickets.
+* These queries are being used by the ticket_queue_handler class. An object of this class holds 2 attributes: the query and the params used for the query.
+* @author Daan Janssens, mentored by Matthew Lagoe
+*/
 class Ticket_Queue{
     
-    private $query;
-    private $params;
+    private $query; /**< The query that loads specific tickets */ 
+    private $params; /**< The parameter array that's being needed by the query */ 
     
+    /**
+    * loads the not yet assigned tickets query into the objects attributes.
+    */
     public function loadAllNotAssignedTickets(){
         $this->query =  "SELECT ticket . * FROM ticket LEFT JOIN assigned ON ticket.TId = assigned.Ticket WHERE assigned.Ticket IS NULL";
         $this->params = array();
     }
     
+    /**
+    * loads the 'all' tickets query into the objects attributes.
+    */
     public function loadAllTickets(){
         $this->query = "SELECT * FROM `ticket`";
         $this->params = array();
     }
     
+    /**
+    * loads the 'all open' tickets query into the objects attributes.
+    */
     public function loadAllOpenTickets(){
         $this->query = "SELECT * FROM ticket INNER JOIN ticket_user ON ticket.Author = ticket_user.TUserId and ticket.Status!=3";
         $this->params = array();
     }
     
+    /**
+    * loads the 'closed' tickets query into the objects attributes.
+    */
     public function loadAllClosedTickets(){
         $this->query = "SELECT * FROM ticket INNER JOIN ticket_user ON ticket.Author = ticket_user.TUserId and ticket.Status=3";
         $this->params = array();
     }
     
+    /**
+    * loads the 'todo' tickets query & params into the objects attributes.
+    * first: find the tickets assigned to the user with status = waiting on support, 
+    * second find all not assigned tickets that aren't forwarded yet.
+    * find all tickets assigned to someone else witht status waiting on support,  with timestamp of last reply > 1 day,
+    * find all non-assigned tickets forwarded to the support groups to which that user belongs
+    * @param $user_id the user's id to whom the tickets should be assigned
+    */
     public function loadToDoTickets($user_id){
         
-        //first: find the tickets assigned to the user with status = waiting on support
-        //second find all not assigned tickets that aren't forwarded yet.        
-        //find all tickets assigned to someone else witht status waiting on support,  with timestamp of last reply > 1 day
-        //find all non-assigned tickets forwarded to the support groups to which that user belongs
         $this->query = "SELECT * FROM `ticket` t LEFT JOIN `assigned` a ON t.TId = a.Ticket LEFT JOIN `ticket_user` tu ON tu.TUserId = a.User LEFT JOIN `forwarded` f ON t.TId = f.Ticket 
         WHERE (tu.ExternId = :user_id AND t.Status = 1) 
         OR (a.Ticket IS NULL AND f.Group IS NULL)
@@ -39,12 +60,26 @@ class Ticket_Queue{
         $this->params = array('user_id' => $user_id);     
     }
     
+    /**
+    * loads the 'tickets asssigned to a user and waiting on support' query & params into the objects attributes.
+    * @param $user_id the user's id to whom the tickets should be assigned
+    */
     public function loadAssignedandWaiting($user_id){
         $this->query = "SELECT * FROM `ticket` t LEFT JOIN `assigned` a ON t.TId = a.Ticket LEFT JOIN `ticket_user` tu ON tu.TUserId = a.User
         WHERE (tu.ExternId = :user_id AND t.Status = 1)";
         $this->params = array('user_id' => $user_id);     
     }
     
+    
+    /**
+    * loads the 'created' query & params into the objects attributes.
+    * This function creates dynamically a query based on the selected features.
+    * @param $who specifies if we want to user the user_id or group_id to form the query.
+    * @param $user_id the user's id to whom the tickets should be assigned/not assigned
+    * @param $group_id  the group's id to whom the tickets should be forwarded/not forwarded
+    * @param $what specifies what kind of tickets we want to return: waiting for support, waiting on user, closed
+    * @param $how specifies if the tickets should be or shouldn't be assigned/forwarded to the group/user selected.
+    */
     public function createQueue($userid, $groupid, $what, $how, $who){
         
         if($who == "user"){
@@ -83,12 +118,21 @@ class Ticket_Queue{
         }  
         $this->query = $query;
         $this->params = $params;
-    }    
+    }
     
+    
+    ////////////////////////////////////////////Getters////////////////////////////////////////////////////
+    
+    /**
+    * get query attribute of the object.
+    */
     public function getQuery(){
         return $this->query;
     }
     
+    /**
+    * get params attribute of the object.
+    */
     public function getParams(){
         return $this->params;
     }
diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_queue_handler.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_queue_handler.php
index 142dc8912..5ea8d8781 100644
--- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_queue_handler.php
+++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_queue_handler.php
@@ -1,14 +1,31 @@
 <?php
-
+/**
+* returns tickets (queues) that are related in some way.
+* This class handles the creation and returning of existing ticket queues. Normally a $_GET['get'] parameter is being used to identify what kind of tickets should be shown.
+* the getTickets() function uses this parameter($input) and uses the ticket_queue class to load the specific query.
+* @author Daan Janssens, mentored by Matthew Lagoe
+*/
 class Ticket_Queue_Handler{
     
-    private $pagination;
-    private $queue;
+    private $pagination; /**< Pagination object, this way only a few tickets (related to that pagenumber) will be shown */ 
+    private $queue; /**< The queue object, being used to get the queries and parameters. */ 
     
+    /**
+    * A constructor.
+    * Instantiates the queue object.
+    */
     function __construct() {
         $this->queue = new Ticket_Queue();
     }
     
+    /**
+    * returns the tickets that are related in someway defined by $input.
+    * The $input parameter should be a string that defines what kind of queue should be loaded. A new pagination object will be instantiated and will load 10 entries,
+    * related to the $_GET['pagenum'] variable.
+    * @param $input identifier that defines what queue to load.
+    * @param $user_id the id of the user that browses the queues, some queues can be depending on this.
+    * @return an array consisting of ticket objects, beware, the author & category of a ticket, are objects on their own (no integers are used this time).
+    */
     public function getTickets($input, $user_id){
      
             switch ($input){
@@ -51,17 +68,29 @@ class Ticket_Queue_Handler{
             
     }
     
+    
+    /**
+    * get pagination attribute of the object.
+    */
     public function getPagination(){
         return $this->pagination;
     }
     
+    /**
+    * creates the queue.
+    * afterwards the getTickets function should be called, else a lot of extra parameters had to be added to the getTickets function..
+    */
     public function createQueue($userid, $groupid, $what, $how, $who){     
         $this->queue->createQueue($userid, $groupid, $what, $how, $who);
     }
     
-    //==================================================================================
-    //Info retrievers about ticket statistics
     
+    ////////////////////////////////////////////Info retrievers about ticket statistics////////////////////////////////////////////////////
+    
+    /**
+    * get the number of tickets in the todo queue for a specific user.
+    * @param $user_id the user being queried
+    */
     public static function getNrOfTicketsToDo($user_id){
         $queueHandler = new Ticket_Queue_Handler();
         $queueHandler->queue->loadToDoTickets($user_id);
@@ -71,6 +100,10 @@ class Ticket_Queue_Handler{
         return $dbl->execute($query,$params)->rowCount();
     }
     
+    /**
+    * get the number of tickets assigned to a specific user and waiting for support.
+    * @param $user_id the user being queried
+    */
     public static function getNrOfTicketsAssignedWaiting($user_id){
         $queueHandler = new Ticket_Queue_Handler();
         $queueHandler->queue->loadAssignedandWaiting($user_id);
@@ -80,6 +113,9 @@ class Ticket_Queue_Handler{
         return $dbl->execute($query,$params)->rowCount();
     }
     
+    /**
+    * get the total number of tickets.
+    */
     public static function getNrOfTickets(){
         $queueHandler = new Ticket_Queue_Handler();
         $queueHandler->queue->loadAllTickets();
@@ -89,6 +125,9 @@ class Ticket_Queue_Handler{
         return $dbl->execute($query,$params)->rowCount();
     }
     
+    /**
+    * get the ticket object of the latest added ticket.
+    */
     public static function getNewestTicket(){
         $dbl = new DBLayer("lib");
         $statement = $dbl->executeWithoutParams("SELECT * FROM `ticket` ORDER BY `TId` DESC LIMIT 1 ");
diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_reply.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_reply.php
index dafbdf74b..8e784543d 100644
--- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_reply.php
+++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_reply.php
@@ -1,16 +1,23 @@
 <?php
-
+/**
+* handles functions related to replies on tickets.
+* @author Daan Janssens, mentored by Matthew Lagoe
+*/
 class Ticket_Reply{
-    private $tReplyId;
-    private $ticket;
-    private $content;
-    private $author;
-    private $timestamp;
-    private $hidden;
+    private $tReplyId; /**< The id of the reply */ 
+    private $ticket; /**< the ticket id related to the reply */ 
+    private $content; /**< the content of the reply */ 
+    private $author; /**< The id of the user that made the reply */ 
+    private $timestamp; /**< The timestamp of the reply */ 
+    private $hidden; /**< indicates if reply should be hidden for normal users or not */ 
     
     ////////////////////////////////////////////Functions////////////////////////////////////////////////////
     
-    //return constructed element based on TCategoryId
+    /**
+    * return constructed element based on TReplyId.
+    * @param $id the Id the reply we want to load.
+    * @return the loaded object.
+    */
     public static function constr_TReplyId( $id) {
         $instance = new self();
         $instance->setTReplyId($id);
@@ -18,22 +25,31 @@ class Ticket_Reply{
     }
     
     
-    //return constructed element based on TCategoryId
+    /**
+    * return all replies on a specific ticket.
+    * @param $ticket_id the id of the ticket of which we want the replies.
+    * @param $view_as_admin if the browsing user is an admin/mod it should be 1, this will also show the hidden replies.
+    * @return an array with ticket_reply objects (beware the author and content are objects on their own, not integers!)
+    */
     public static function getRepliesOfTicket( $ticket_id, $view_as_admin) {
         $dbl = new DBLayer("lib");
         $statement = $dbl->execute("SELECT * FROM ticket_reply INNER JOIN ticket_content INNER JOIN ticket_user ON ticket_reply.Content = ticket_content.TContentId and ticket_reply.Ticket=:id and ticket_user.TUserId = ticket_reply.Author ORDER BY ticket_reply.TReplyId ASC", array('id' => $ticket_id));
         $row = $statement->fetchAll();
         $result = Array();
         foreach($row as $tReply){
+            //only add hidden replies if the user is a mod/admin
             if(! $tReply['Hidden'] || $view_as_admin){
+                //load author
                 $instanceAuthor = Ticket_User::constr_TUserId($tReply['Author']);
                 $instanceAuthor->setExternId($tReply['ExternId']);
                 $instanceAuthor->setPermission($tReply['Permission']);
                 
+                //load content
                 $instanceContent = new Ticket_Content();
                 $instanceContent->setTContentId($tReply['TContentId']);
                 $instanceContent->setContent($tReply['Content']);
                 
+                //load reply and add the author and content object in it.
                 $instanceReply = new self();
                 $instanceReply->setTReplyId($tReply['TReplyId']);
                 $instanceReply->setTimestamp($tReply['Timestamp']);
@@ -47,6 +63,16 @@ class Ticket_Reply{
         return $result; 
     }
     
+    /**
+    * creates a new reply on a ticket.
+    * Creates a ticket_content entry and links it with a new created ticket_reply, a log entry will be written about this.
+    * In case the ticket creator replies on a ticket, he will set the status by default to 'waiting on support'.
+    * @param $content the content of the reply
+    * @param $author the id of the reply creator.
+    * @param $ticket_id the id of the ticket of which we want the replies.
+    * @param $hidden should be 0 or 1
+    * @param $ticket_creator the ticket's starter his id.
+    */
     public static function createReply($content, $author, $ticket_id , $hidden, $ticket_creator){
         $ticket_content = new Ticket_Content();
         $ticket_content->setContent($content);
@@ -66,12 +92,19 @@ class Ticket_Reply{
     }
     
     ////////////////////////////////////////////Methods////////////////////////////////////////////////////
-    
+
+    /**
+    * A constructor.
+    * Empty constructor
+    */
     public function __construct() {
     }
 
 
-    //Set ticket_reply object
+    /**
+    * sets the object's attributes.
+    * @param $values should be an array.
+    */
     public function set($values){
         $this->setTicket($values['Ticket']);
         $this->setContent($values['Content']);
@@ -84,7 +117,10 @@ class Ticket_Reply{
         }
     }
     
-    //create ticket by writing private data to DB.
+    /**
+    * creates a new 'ticket_reply' entry.
+    * this method will use the object's attributes for creating a new 'ticket_reply' entry in the database (the now() function will create the timestamp).
+    */
     public function create(){
         $dbl = new DBLayer("lib");
         $query = "INSERT INTO ticket_reply (Ticket, Content, Author, Timestamp, Hidden) VALUES (:ticket, :content, :author, now(), :hidden)";
@@ -92,7 +128,11 @@ class Ticket_Reply{
         $this->tReplyId = $dbl->executeReturnId($query, $values); 
     }
 
-    //return constructed element based on TId
+    /**
+    * loads the object's attributes.
+    * loads the object's attributes by giving a ticket_reply's id.
+    * @param $id the id of the ticket_reply that should be loaded
+    */
     public function load_With_TReplyId( $id) {
         $dbl = new DBLayer("lib");
         $statement = $dbl->execute("SELECT * FROM ticket_reply WHERE TReplyId=:id", array('id' => $id));
@@ -105,7 +145,9 @@ class Ticket_Reply{
         $this->hidden = $row['Hidden'];
     }
     
-    //update private data to DB.
+    /**
+    * updates a ticket_reply entry based on the objects attributes.
+    */
     public function update(){
         $dbl = new DBLayer("lib");
         $query = "UPDATE ticket SET Ticket = :ticket, Content = :content, Author = :author, Timestamp = :timestamp, Hidden = :hidden WHERE TReplyId=:id";
@@ -115,56 +157,95 @@ class Ticket_Reply{
     
     ////////////////////////////////////////////Getters////////////////////////////////////////////////////
      
+    /**
+    * get ticket attribute of the object.
+    */
     public function getTicket(){
         return $this->ticket;
     }
-   
-   
+    
+    /**
+    * get content attribute of the object.
+    */
     public function getContent(){
         return $this->content;
     }
-    
+
+    /**
+    * get author attribute of the object.
+    */
     public function getAuthor(){
         return $this->author;
     }
     
+    /**
+    * get timestamp attribute of the object.
+    * The output format is defined by the Helpers class function, outputTime().
+    */
     public function getTimestamp(){
         return Helpers::outputTime($this->timestamp);
     }
     
-    
+    /**
+    * get tReplyId attribute of the object.
+    */
     public function getTReplyId(){
         return $this->tReplyId;
     }
    
+    /**
+    * get hidden attribute of the object.
+    */
     public function getHidden(){
         return $this->hidden;
     } 
     
     ////////////////////////////////////////////Setters////////////////////////////////////////////////////
      
+    /**
+    * set ticket attribute of the object.
+    * @param $t integer id of the ticket
+    */
     public function setTicket($t){
         $this->ticket = $t;
     }
    
-   
+    /**
+    * set content attribute of the object.
+    * @param $c integer id of the ticket_content entry
+    */
     public function setContent($c){
         $this->content = $c;
     }
     
+    /**
+    * set author attribute of the object.
+    * @param $a integer id of the user
+    */
     public function setAuthor($a){
         $this->author =  $a;
     }
     
+    /**
+    * set timestamp attribute of the object.
+    * @param $t timestamp of the reply
+    */
     public function setTimestamp($t){
         $this->timestamp = $t;
     }
     
-    
+    /**
+    * set tReplyId attribute of the object.
+    * @param $i integer id of the ticket_reply
+    */
     public function setTReplyId($i){
         $this->tReplyId = $i;
     }
         
+    /**
+    * set hidden attribute of the object.
+    * @param $h should be 0 or 1
+    */
     public function setHidden($h){
         $this->hidden = $h;
     }
diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_user.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_user.php
index 6772dd216..46125e284 100644
--- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_user.php
+++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/ticket_user.php
@@ -1,13 +1,24 @@
 <?php
+/**
+* user entry point in the ticket system.
+* The ticket_user makes a link between the entire ticket system's lib db and the www user, which is stored in another db (this is the external ID).
+* The externalID could be the ID of a drupal user or wordpress user,.. The ticket_user also stores the permission of that user, this way the permission system
+* is inside the lib itself and can be used in any www version that you like. permission 1 = user, 2 = mod, 3 = admin.
+* @author Daan Janssens, mentored by Matthew Lagoe
+*/
 class Ticket_User{
     
-    private $tUserId;
-    private $permission;
-    private $externId;
+    private $tUserId;  /**< The id of the user inside the ticket system*/ 
+    private $permission;  /**< The permission of the user */ 
+    private $externId;  /**< The id of the user account in the www (could be drupal,...) that is linked to the ticket_user */ 
     
     ////////////////////////////////////////////Functions////////////////////////////////////////////////////
     
-    //Creates a ticket_user in the DB
+    /**
+    * create a new ticket user.
+    * @param $extern_id the id of the user account in the www version (drupal,...)
+    * @param $permission the permission that will be given to the user. 1=user, 2=mod, 3=admin
+    */
     public static function createTicketUser( $extern_id, $permission) {
         $dbl = new DBLayer("lib");
         $query = "INSERT INTO ticket_user (Permission, ExternId) VALUES (:perm, :ext_id)";
@@ -16,6 +27,12 @@ class Ticket_User{
 
     }
     
+    
+    /**
+    * check if a ticket_user object is a mod or not.
+    * @param $user the ticket_user object itself
+    * @return true or false
+    */
     public static function isMod($user){
         if(isset($user) && $user->getPermission() > 1){
             return true;
@@ -23,6 +40,12 @@ class Ticket_User{
         return false;
     }
     
+    
+    /**
+    * check if a ticket_user object is an admin or not.
+    * @param $user the ticket_user object itself
+    * @return true or false
+    */
     public static function isAdmin($user){
         if(isset($user) && $user->getPermission() == 3){
             return true;
@@ -30,7 +53,12 @@ class Ticket_User{
         return false;
     }
     
-    //return constructed element based on TUserId
+    
+    /**
+    * return constructed ticket_user object based on TUserId.
+    * @param $id the TUserId of the entry.
+    * @return constructed ticket_user object
+    */
     public static function constr_TUserId( $id) {
         $instance = new self();
         $instance->setTUserId($id);
@@ -38,7 +66,11 @@ class Ticket_User{
     
     }
     
-    //return all mods/admins
+    
+    /**
+    * return a list of all mods/admins.
+    * @return an array consisting of ticket_user objects that are mods & admins.
+    */
     public static function getModsAndAdmins() {
         $dbl = new DBLayer("lib");
         $statement = $dbl->executeWithoutParams("SELECT * FROM `ticket_user` WHERE `Permission` > 1");
@@ -52,7 +84,12 @@ class Ticket_User{
         return $result; 
     }
     
-    //return constructed element based on ExternId
+    
+    /**
+    * return constructed ticket_user object based on ExternId.
+    * @param $id the ExternId of the entry.
+    * @return constructed ticket_user object
+    */
     public static function constr_ExternId( $id) {
         $instance = new self();
         $dbl = new DBLayer("lib");
@@ -62,9 +99,14 @@ class Ticket_User{
         $instance->permission = $row['Permission'];
         $instance->externId = $row['ExternId'];
         return $instance;
-
     }
     
+    
+    /**
+    * change the permission of a ticket_user.
+    * @param $user_id the TUserId of the entry.
+    * @param $perm the new permission value.
+    */
     public static function change_permission($user_id, $perm){
         $user = new Ticket_User();
         $user->load_With_TUserId($user_id);
@@ -73,6 +115,11 @@ class Ticket_User{
     }
     
     
+    /**
+    * return the email address of a ticket_user.
+    * @param $id the TUserId of the entry.
+    * @return string containing the email address of that user.
+    */
     public static function get_email_by_user_id($id){
         $user = new Ticket_User();
         $user->load_With_TUserId($id);
@@ -81,6 +128,11 @@ class Ticket_User{
     }
     
     
+    /**
+    * return the username of a ticket_user.
+    * @param $id the TUserId of the entry.
+    * @return string containing username of that user.
+    */
     public static function get_username_from_id($id){
         $user = new Ticket_User();
         $user->load_With_TUserId($id);
@@ -89,13 +141,22 @@ class Ticket_User{
     }
     
     
+    /**
+    * return the TUserId of a ticket_user by giving a username.
+    * @param $username the username of a user.
+    * @return the TUserId related to that username.
+    */
     public static function get_id_from_username($username){
         $externId = WebUsers::getId($username);
         $user = Ticket_User::constr_ExternId($externId);
         return $user->getTUserId();   
     }
     
-    
+    /**
+    * return the ticket_user id from an email address.
+    * @param $email the emailaddress of a user.
+    * @return the ticket_user id related to that email address, in case none, return "FALSE".
+    */
     public static function get_id_from_email($email){
         $webUserId = WebUsers::getIdFromEmail($email);
         if($webUserId != "FALSE"){
@@ -108,10 +169,19 @@ class Ticket_User{
     
     
     ////////////////////////////////////////////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('TUserId' => id, 'Permission' => perm, 'ExternId' => ext_id).
+    */
     public function set($values) {
         $this->setTUserId($values['TUserId']);
         $this->setPermission($values['Permission']);
@@ -119,7 +189,11 @@ class Ticket_User{
     }
     
     
-    //return constructed element based on TUserId
+    /**
+    * loads the object's attributes.
+    * loads the object's attributes by giving a TUserId.
+    * @param $id the id of the ticket_user that should be loaded
+    */
     public function load_With_TUserId( $id) {
         $dbl = new DBLayer("lib");
         $statement = $dbl->execute("SELECT * FROM ticket_user WHERE TUserId=:id", array('id' => $id));
@@ -129,7 +203,10 @@ class Ticket_User{
         $this->externId = $row['ExternId'];
     } 
     
-    //update private data to DB.
+    
+    /**
+    * update the object's attributes to the db.
+    */
     public function update(){
         $dbl = new DBLayer("lib");
         $query = "UPDATE ticket_user SET Permission = :perm, ExternId = :ext_id WHERE TUserId=:id";
@@ -139,16 +216,23 @@ class Ticket_User{
     
     ////////////////////////////////////////////Getters////////////////////////////////////////////////////
     
+    /**
+    * get permission attribute of the object.
+    */
     public function getPermission(){
         return $this->permission;
     }
    
-   
+    /**
+    * get externId attribute of the object.
+    */
     public function getExternId(){
         return $this->externId;
     }
     
-    
+    /**
+    * get tUserId attribute of the object.
+    */
     public function getTUserId(){
         return $this->tUserId;
     }
@@ -156,15 +240,27 @@ class Ticket_User{
     
     ////////////////////////////////////////////Setters////////////////////////////////////////////////////
     
+    /**
+    * set permission attribute of the object.
+    * @param $perm integer that indicates the permission level. (1= user, 2= mod, 3= admin)
+    */
     public function setPermission($perm){
         $this->permission = $perm;
     }
    
    
+    /**
+    * set externId attribute of the object.
+    * @param $id the external id.
+    */  
     public function setExternId($id){
         $this->externId = $id;
     }
     
+    /**
+    * set tUserId attribute of the object.
+    * @param $id the ticket_user id
+    */
     public function setTUserId($id){
         $this->tUserId= $id;
     }
diff --git a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/users.php b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/users.php
index 3eb67b97e..1768f62ce 100644
--- a/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/users.php
+++ b/code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/users.php
@@ -1,10 +1,15 @@
 <?php
+/**
+* handles basic user registration & management functions (shard related).
+* The Users class is the basis class of WebUsers, this class provides functions being used by all CMS's and our own www version. The WebUsers class however needs to be reimplemented
+* by using the CMS's it's funcionality. This class handles the writing to the shard db mainly, and in case it's offline: writing to the ams_querycache.
+* @author Daan Janssens, mentored by Matthew Lagoe
+*/
 class Users{
      
      /**
-     * Function check_register
-     *
-     * @takes $array with username,password and email
+     * checks if entered values before registering are valid.
+     * @param $array with Username,Password, ConfirmPass and Email.
      * @return string Info: Returns a string, if input data is valid then "success" is returned, else an array with errors
      */ 
      public function check_Register($values){
@@ -63,15 +68,12 @@ class Users{
 
      }
      
-     
-
-
-    /**
-     * Function checkUser
-     *
-     * @takes $username
+    
+     /**
+     * checks if entered username is valid.
+     * @param $username the username that the user wants to use.
      * @return string Info: Returns a string based on if the username is valid, if valid then "success" is returned
-     */
+     */ 
      public function checkUser( $username )
      {
           if ( isset( $username ) ){
@@ -93,9 +95,9 @@ class Users{
      }
          
      /**
-     * Function checkUserNameExists
-     *
-     * @takes $username
+     * check if username already exists.
+     * This is the base function, it should be overwritten by the WebUsers class.
+     * @param $username the username
      * @return string Info: Returns true or false if the user is in the www db.
      */
      protected function checkUserNameExists($username){
@@ -106,9 +108,8 @@ class Users{
          
          
     /**
-     * Function checkPassword
-     *
-     * @takes $pass
+     * checks if the password is valid.
+     * @param $pass the password willing to be used.
      * @return string Info: Returns a string based on if the password is valid, if valid then "success" is returned
      */
      public function checkPassword( $pass )
@@ -129,9 +130,10 @@ class Users{
          
          
     /**
-     * Function confirmPassword
-     *
-     * @takes $pass
+     * checks if the confirmPassword matches the original.
+     * @param $pass_result the result of the previous password check.
+     * @param $pass the original pass.
+     * @param $confirmpass the confirmation password.
      * @return string Info: Verify's $_POST["Password"] is the same as $_POST["ConfirmPass"]
      */
      private function confirmPassword($pass_result,$pass,$confirmpass)
@@ -151,10 +153,9 @@ class Users{
      
      
     /**
-     * Function checkEmail
-     *
-     * @takes $email
-     * @return
+     * wrapper to check if the email address is valid.
+     * @param $email the email address
+     * @return "success", else in case it isn't valid an error will be returned.
      */
      public function checkEmail( $email )
     {
@@ -174,10 +175,10 @@ class Users{
 
 
      /**
-     * Function checkEmailExists
-     *
-     * @takes $username
-     * @return string Info: Returns true or false if the user is in the www db.
+     * check if email already exists.
+     * This is the base function, it should be overwritten by the WebUsers class.
+     * @param $email the email address
+     * @return string Info: Returns true or false if the email is in the www db.
      */
      protected function checkEmailExists($email){
           //TODO: You should overwrite this method with your own version!
@@ -186,11 +187,10 @@ class Users{
      }
          
          
-    /**
-     * Function validEmail
-     *
-     * @takes $email
-     * @return true or false depending on if its a valid email format.
+     /**
+     * check if the emailaddress structure is valid.
+     * @param $email the email address
+     * @return true or false
      */
      public function validEmail( $email ){
           $isValid = true;
@@ -238,9 +238,8 @@ class Users{
 
 
      /**
-     * Function generateSALT
-     *
-     * @takes $length, which is by default 2
+     * generate a SALT.
+     * @param $length, which is by default 2
      * @return a random salt of 2 chars
      */
      public static function generateSALT( $length = 2 )
@@ -278,10 +277,10 @@ class Users{
      
 
 
-    /**
-     * Function create
-     *
-     * @takes $array with name,pass and mail
+     /**
+     * creates a user in the shard.
+     * incase the shard is offline it will place it in the ams_querycache.
+     * @param $values with name,pass and mail
      * @return ok if it's get correctly added to the shard, else return lib offline and put in libDB, if libDB is also offline return liboffline.
      */
      public static function createUser($values, $user_id){     
@@ -308,6 +307,11 @@ class Users{
 
      }
      
+     /**
+     * creates permissions in the shard db for a user.
+     * incase the shard is offline it will place it in the ams_querycache.
+     * @param $pvalues with username
+     */
      public static function createPermissions($pvalues) {
           
           try {
@@ -333,10 +337,22 @@ class Users{
      }
      
      
+     /**
+     * check if username and password matches.
+     * This is the base function, it should be overwritten by the WebUsers class.
+     * @param $user the inserted username
+     * @param $pass the inserted password
+     */
      protected function checkLoginMatch($user,$pass){
           print('This is the base class!');
      }
      
+     /**
+     * check if the changing of a password is valid.
+     * a mod/admin doesn't has to fill in the previous password when he wants to change the password, however for changing his own password he has to fill it in.
+     * @param $values an array containing the CurrentPass, ConfirmNewPass, NewPass and adminChangesOthers
+     * @return if it is valid "success will be returned, else an array with errors will be returned.
+     */
      public function check_change_password($values){
           //if admin isn't changing others
           if(!$values['adminChangesOther']){
@@ -390,6 +406,13 @@ class Users{
           }
      }
      
+     /**
+     * sets the shards password.
+     * in case the shard is offline, the entry will be stored in the ams_querycache.
+     * @param $user the usersname of the account of which we want to change the password.
+     * @param $pass the new password.
+     * @return ok if it worked, if the lib or shard is offline it will return liboffline or shardoffline.
+     */
      protected function setAmsPassword($user, $pass){
           
            $values = Array('user' => $user, 'pass' => $pass);
@@ -413,6 +436,13 @@ class Users{
           } 
      }
      
+     /**
+     * sets the shards email.
+     * in case the shard is offline, the entry will be stored in the ams_querycache.
+     * @param $user the usersname of the account of which we want to change the emailaddress.
+     * @param $mail the new email address
+     * @return ok if it worked, if the lib or shard is offline it will return liboffline or shardoffline.
+     */
      protected function setAmsEmail($user, $mail){
           
            $values = Array('user' => $user, 'mail' => $mail);