Even more docs! writing documentation sucks..

--HG--
branch : quitta-gsoc-2013

code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/pagination.php

@@ -1,12 +1,28 @@
 <?php
-
+/**
+* Handles returning arrays based on a given pagenumber.
+* By specifing a $_GET['pagenum'] or if not(page = 1 will be used) a few elements from a specific query will be returned. Not all elements have to be loaded into objects, only
+* the elements needed for that specific page, this is a good thing performance wise. This is done by passign the query to the constructor and specifying how many you want to display.
+* @author Daan Janssens, mentored by Matthew Lagoe
+*/
 class Pagination{
     
-    private $element_array;
+    private $element_array; /**< Array containing the elements that are extracted for that specific page number */ 
-    private $last;
+    private $last; /**< The last page number */ 
-    private $current;
+    private $current; /**< The current page number (read from $_GET['pagenum']) */ 
-    private $amountOfRows;
+    private $amountOfRows;  /**< Total amount of rows that a query would return (if no limits would be used) */ 
     
+    /**
+    * Constructor.
+    * will fetch the correct elements that match to a specific page (specified by the $_GET['pagenum'] variable). The query has to be passed as a string to the function
+    * that way it will only load the specific elements that are related to the pagenumber. The $params, parameter is optional and is used to pass the parameters for the query.
+    * The result class will be used to instantiate the found elements with, their set() function will be called. The class  its getters can be later used to get the info out of the object.
+    * @param $query the query to be paginated
+    * @param $db the db on which the query should be performed
+    * @param $nrDisplayed the amount of elements that should be displayed /page
+    * @param $resultClass the elements that should be returned should be of that specific class.
+    * @param $params the parameters used by the query (optional)
+    */
     function __construct($query, $db, $nrDisplayed, $resultClass, $params = array()) {
         if (!(isset($_GET['pagenum']))){ 
             $this->current= 1; 
@@ -52,22 +68,47 @@ class Pagination{
     }
     
     
+    /**
+    * return the number of the 'last' object attribute
+    * @return the number of the last page
+    */
     public function getLast(){
         return $this->last;
     }
     
+    
+    /**
+    * return the number of the 'current' object attribute
+    * @return the number of the current page
+    */
     public function getCurrent(){
         return $this->current;
     }
     
+    
+    /**
+    * return the elements array of the object
+    * @return the elements of a specific page (these are instantiations of the class passed as parameter ($resultClass) to the constructor)
+    */
     public function getElements(){
         return $this->element_array;
     }
     
+    
+    /**
+    * return total amount of rows for the original query
+    * @return the total amount of rows for the original query
+    */
     public function getAmountOfRows(){
         return $this->amountOfRows;
     }
     
+    /**
+    * return the page links.
+    * (for browsing the pages, placed under a table for example) the $nrOfLinks parameter specifies the amount of links you want to return.
+    * it will show the links closest to the current page on both sides (in case one side can't show more, it will show more on the other side)
+    * @return an array of integerswhich refer to the clickable pagenumbers for browsing other pages.
+    */
     public function getLinks($nrOfLinks){
         $pageLinks = Array();
         //if amount of showable links is greater than the amount of pages: show all!

code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/querycache.php

@@ -1,21 +1,37 @@
 <?php
 
+/**
+* handler for storing changes when shard is offline.
+* @todo make sure that the querycache class is being used by the sync class and also for inserting the queries themselfs into it.
+* Atm this class isn't used yet if I remember correctly
+* @author Daan Janssens, mentored by Matthew Lagoe
+*/
+
 class Querycache{
     
-    private $SID;
+    private $SID;  /**< The queries ID */ 
-    private $type;
+    private $type;  /**< The type of query*/ 
-    private $query;
+    private $query;  /**< The query itself (json encoded) */ 
-    private $db;
+    private $db;  /**< the db where the query  should be performed */ 
     
     ////////////////////////////////////////////Functions////////////////////////////////////////////////////
     
     
     
     ////////////////////////////////////////////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('SID' => sid, 'type' => type, 'query' => query, 'db' => db).
+    */
     public function set($values) {
         $this->setSID($values['SID']);
         $this->setType($values['type']);
@@ -24,7 +40,11 @@ class Querycache{
     }
     
     
-    //return constructed element based on SID
+    /**
+    * loads the object's attributes.
+    * loads the object's attributes by giving a SID as parameter
+    * @param $id the id of the querycaches row
+    */
     public function load_With_SID( $id) {
         $dbl = new DBLayer("lib");
         $statement = $dbl->execute("SELECT * FROM ams_querycache WHERE SID=:id", array('id' => $id));
@@ -33,7 +53,9 @@ class Querycache{
     } 
     
     
-    //update private data to DB.
+    /**
+    * updates the entry.
+    */
     public function update(){
         $dbl = new DBLayer("lib");
         $query = "UPDATE ams_querycache SET type= :t, query = :q, db = :d WHERE SID=:id";
@@ -43,39 +65,64 @@ class Querycache{
     
     ////////////////////////////////////////////Getters////////////////////////////////////////////////////
     
+    /**
+    * get SID attribute of the object.
+    */
     public function getSID(){
         return $this->SID;
     }
    
-   
+    /**
+    * get type attribute of the object.
+    */
     public function getType(){
         return $this->type;
     }
     
-    
+    /**
+    * get query attribute of the object.
+    */
     public function getQuery(){
         return $this->query;
     }
     
+    /**
+    * get db attribute of the object.
+    */
     public function getDb(){
         return $this->db;
     }
     
     ////////////////////////////////////////////Setters////////////////////////////////////////////////////
     
+    /**
+    * set SID attribute of the object.
+    * @param $s integer id 
+    */
     public function setSID($s){
         $this->SID = $s;
     }
    
-   
+    /**
+    * set type attribute of the object.
+    * @param $t type of the query, could be changePassword, changePermissions, changeEmail, createUser
+    */
     public function setType($t){
         $this->type = $t;
     }
     
+    /**
+    * set query attribute of the object.
+    * @param $q query string
+    */
     public function setQuery($q){
         $this->query= $q;
     }
     
+    /**
+    * set db attribute of the object.
+    * @param $d the name of the database in the config global var that we want to use.
+    */
     public function setDb($d){
         $this->db= $d;
     }

code/ryzom/tools/server/ryzom_ams/ams_lib/autoload/support_group.php

@@ -1,18 +1,27 @@
 <?php
-
+/**
+* groups moderators & admins together. A Support Group is a group of people with the same skills or knowledge. A typical example will be the (Developers group, webteam group, management, etc..)
+* The idea is that tickets can be forwarded to a group of persons that might be able to answer that specific question. Support Groups are also the key of handling the emails, because the email addresses
+* of the support groups will be used by the Mail_Handler class.
+* @author Daan Janssens, mentored by Matthew Lagoe
+*/
 class Support_Group{
     
-    private $sGroupId;
+    private $sGroupId;  /**< The id of the support group */ 
-    private $name;
+    private $name;  /**< The name of the support group */ 
-    private $tag;
+    private $tag; /**< The tag of the support group, a tag is max 4 letters big, and will be used in the future as easy reference to indicate what group it is refered to (eg [DEV]) */ 
-    private $groupEmail;
+    private $groupEmail; /**< The email address of the group */ 
-    private $iMAP_MailServer;
+    private $iMAP_MailServer; /**< The imap server connection string */ 
-    private $iMAP_Username;
+    private $iMAP_Username; /**< The imap username of the account */ 
-    private $iMAP_Password;
+    private $iMAP_Password; /**< The imap matching password*/ 
     
     ////////////////////////////////////////////Functions////////////////////////////////////////////////////
     
-    //return group
+    /**
+    * return a specific support_group object.
+    * @param $id the id of the support group that we want to return
+    * @return a support_group object.
+    */
     public static function getGroup($id) {
         $dbl = new DBLayer("lib");
         $statement = $dbl->execute("SELECT * FROM support_group WHERE SGroupId = :id", array('id' => $id));
@@ -23,7 +32,11 @@ class Support_Group{
     
     }
     
-    //return all groups
+    
+    /**
+    * return all support_group objects.
+    * @return an array containing all support_group objects.
+    */
     public static function getGroups() {
         $dbl = new DBLayer("lib");
         $statement = $dbl->executeWithoutParams("SELECT * FROM support_group ORDER BY Name ASC");
@@ -38,7 +51,14 @@ class Support_Group{
         return $result; 
     }
     
-    //wrapper for creating a support group
+    
+    /**
+    * Wrapper for creating a support group.
+    * It will check if the support group doesn't exist yet, if the tag or name already exists then NAME_TAKEN  or TAG_TAKEN will be returned.
+    * If the name is bigger than 20 characters or smaller than 4 and the tag greater than 7 or smaller than 2 a SIZE_ERROR will be returned.
+    * Else it will return SUCCESS
+    * @return a string that specifies if it was a success or not (SUCCESS, SIZE_ERROR, NAME_TAKEN or TAG_TAKEN )
+    */
     public static function createSupportGroup( $name, $tag, $groupemail, $imap_mailserver, $imap_username, $imap_password) {
         
         if(strlen($name) < 21 && strlen($name) > 4 &&strlen($tag) < 8  && strlen($tag) > 1 ){
@@ -70,7 +90,12 @@ class Support_Group{
         } 
     }
 
-    //check if group exists
+    /**
+    * check if support group name/tag doesn't exist yet.
+    * @param $name the name of the group we want to check
+    * @param $tag the tag of the group we want to check
+    * @return if name is already taken return NAME_TAKEN, else if tag is already taken return TAG_TAKEN, else return success.
+    */
     public static function supportGroup_EntryNotExists( $name, $tag) {
         $dbl = new DBLayer("lib");
         //check if name is already used
@@ -85,7 +110,11 @@ class Support_Group{
     }
 
 
-    //check if group exists
+    /**
+    * check if support group entry coupled to a given id exist or not.
+    * @param $id the id of the group we want to check
+    * @return true or false.
+    */
     public static function supportGroup_Exists( $id) {
         $dbl = new DBLayer("lib");
         //check if supportgroup id exist
@@ -97,14 +126,23 @@ class Support_Group{
     }
     
     
-    //return constructed element based on SGroupId
+    /**
+    * construct an object based on the SGroupId.
+    * @param $id the id of the group we want to construct
+    * @return the constructed support group object
+    */
     public static function constr_SGroupId( $id) {
         $instance = new self();
         $instance->setSGroup($id);
         return $instance;
     }
     
-    //returns list of all users that are enlisted to a support group
+
+    /**
+    * get list of all users that are enlisted to a support group.
+    * @param $id the id of the group we want to query
+    * @return an array of ticket_user objects that are in the support group.
+    */
     public static function getAllUsersOfSupportGroup($group_id) {
         $dbl = new DBLayer("lib");
         $statement = $dbl->execute("SELECT * FROM `in_support_group` INNER JOIN `ticket_user` ON ticket_user.TUserId = in_support_group.User WHERE in_support_group.Group=:id", array('id' => $group_id));
@@ -120,7 +158,13 @@ class Support_Group{
         return $result; 
     }
      
-    //wrapper for adding user to a support group
+    
+    /**
+    * wrapper for deleting a support group.
+    * We will first check if the group really exists, if not than "GROUP_NOT_EXISING" will be returned.
+    * @param $group_id the id of the group we want to delete
+    * @return an array of ticket_user objects that are in the support group.
+    */
     public static function deleteSupportGroup($group_id) {
         
         //check if group id exists
@@ -135,7 +179,15 @@ class Support_Group{
             
     }
     
-    //wrapper for adding user to a support group
+    /**
+    * wrapper for deleting a user that's in a specified support group.
+    * We will first check if the group really exists, if not than "GROUP_NOT_EXISING" will be returned.
+    * Afterwards we will check if the user exists in the support group, if not "USER_NOT_IN_GROUP" will be returned.
+    * Else the users entry in the in_support_group table will be deleted and "SUCCESS" will be returned.
+    * @param $user_id the id of the user we want to remove out of the group.
+    * @param $group_id the id of the group the user should be in
+    * @return a string (SUCCESS, USER_NOT_IN_GROUP or GROUP_NOT_EXISTING)
+    */
     public static function deleteUserOfSupportGroup( $user_id, $group_id) {
         
         //check if group id exists
@@ -164,7 +216,16 @@ class Support_Group{
             
     }
     
-    //wrapper for adding user to a support group
+    
+    /**
+    * wrapper for adding a user to a specified support group.
+    * We will first check if the group really exists, if not than "GROUP_NOT_EXISING" will be returned.
+    * Afterwards we will check if the user exists in the support group, if so "ALREADY_ADDED" will be returned.
+    * Else the user will be added to the in_support_group table and "SUCCESS" will be returned.
+    * @param $user_id the id of the user we want to add to the group.
+    * @param $group_id the id of the group the user wants to be in
+    * @return a string (SUCCESS, ALREADY_ADDED or GROUP_NOT_EXISTING)
+    */
     public static function addUserToSupportGroup( $user_id, $group_id) {
         //check if group id exists
         if (self::supportGroup_Exists($group_id)){
@@ -191,7 +252,12 @@ class Support_Group{
             
     }
     
-    //returns list of all category objects
+    
+    /**
+    * return all support_group objects.
+    * @return an array containing all support_group objects.
+    * @deprecated should be removed in the future, because getGroups does the same.
+    */
     public static function getAllSupportGroups() {
         $dbl = new DBLayer("lib");
         $statement = $dbl->executeWithoutParams("SELECT * FROM `support_group`");
@@ -206,10 +272,19 @@ class Support_Group{
     }
     ////////////////////////////////////////////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('SGroupId' => groupid, 'Name' => name, 'Tag' => tag, 'GroupEmail' => mail, 'IMAP_MailServer' => server, 'IMAP_Username' => username,'IMAP_Password' => pass).
+    */
     public function set($values) {
         $this->setSGroupId($values['SGroupId']);
         $this->setName($values['Name']);
@@ -220,6 +295,11 @@ class Support_Group{
         $this->setIMAP_Password($values['IMAP_Password']);
     }
     
+    
+    /**
+    * creates a new 'support_group' entry.
+    * this method will use the object's attributes for creating a new 'support_group' entry in the database.
+    */
     public function create() {
         $dbl = new DBLayer("lib");
         $query = "INSERT INTO support_group (Name, Tag, GroupEmail, IMAP_MailServer, IMAP_Username, IMAP_Password) VALUES (:name, :tag, :groupemail, :imap_mailserver, :imap_username, :imap_password)";
@@ -227,7 +307,12 @@ class Support_Group{
         $dbl->execute($query, $values);
     } 
 
-    //Load with sGroupId
+    
+    /**
+    * loads the object's attributes.
+    * loads the object's attributes by giving a group id, it will put the matching groups attributes in the object.
+    * @param $id the id of the support group that should be loaded
+    */
     public function load_With_SGroupId( $id) {
         $dbl = new DBLayer("lib");
         $statement = $dbl->execute("SELECT * FROM `support_group` WHERE `SGroupId` = :id", array('id' => $id));
@@ -236,7 +321,9 @@ class Support_Group{
     }
     
     
-    //update private data to DB.
+    /**
+    * update the objects attributes to the db.
+    */
     public function update(){
         $dbl = new DBLayer("lib");
         $query = "UPDATE `support_group` SET `Name` = :name, `Tag` = :tag, `GroupEmail` = :groupemail, `IMAP_MailServer` = :mailserver, `IMAP_Username` = :username, `IMAP_Password` = :password WHERE `SGroupId` = :id";
@@ -244,7 +331,11 @@ class Support_Group{
         $statement = $dbl->execute($query, $values);
     }
     
-    //delete entry
+    
+    /**
+    * deletes an existing 'support_group' entry.
+    * this method will use the object's attributes for deleting an existing 'support_group' entry in the database.
+    */
     public function delete(){
         $dbl = new DBLayer("lib");
         $query = "DELETE FROM `support_group` WHERE `SGroupId` = :id";
@@ -254,59 +345,108 @@ class Support_Group{
     
     ////////////////////////////////////////////Getters////////////////////////////////////////////////////
     
+    /**
+    * get sGroupId attribute of the object.
+    */
     public function getSGroupId(){
         return $this->sGroupId;
     }
     
+    /**
+    * get name attribute of the object.
+    */
     public function getName(){
         return $this->name;
     }
     
+    /**
+    * get tag attribute of the object.
+    */
     public function getTag(){
         return $this->tag;
     }
     
+    /**
+    * get groupEmail attribute of the object.
+    */
     public function getGroupEmail(){
         return $this->groupEmail;
     }
     
+    /**
+    * get iMAP_MailServer attribute of the object.
+    */
     public function getIMAP_MailServer(){
         return $this->iMAP_MailServer;
     }
     
+    /**
+    * get iMAP_Username attribute of the object.
+    */
     public function getIMAP_Username(){
         return $this->iMAP_Username;
     }
     
+    /**
+    * get iMAP_Password attribute of the object.
+    */
     public function getIMAP_Password(){
         return $this->iMap_Password;
     }
     ////////////////////////////////////////////Setters////////////////////////////////////////////////////
      
+    /**
+    * set sGroupId attribute of the object.
+    * @param $id integer id of the group
+    */
     public function setSGroupId($id){
         $this->sGroupId = $id;
     }
     
+    /**
+    * set name attribute of the object.
+    * @param $n name of the group
+    */
     public function setName($n){
         $this->name = $n;
     }
     
+    /**
+    * set tag attribute of the object.
+    * @param $t tag of the group
+    */
     public function setTag($t){
         $this->tag = $t;
     }
    
+    /**
+    * set groupEmail attribute of the object.
+    * @param $ge email of the group
+    */
     public function setGroupEmail($ge){
         $this->groupEmail = $ge;
     }
     
+    /**
+    * set iMAP_MailServer attribute of the object.
+    * @param $ms mailserver of the group
+    */
     public function setIMAP_MailServer($ms){
         $this->iMAP_MailServer = $ms;
     }
     
+    /**
+    * set iMAP_Username attribute of the object.
+    * @param $u imap username of the group
+    */
     public function setIMAP_Username($u){
         $this->iMAP_Username = $u;
     }
     
+    /**
+    * set iMAP_Password attribute of the object.
+    * @param $p imap password of the group
+    */
     public function setIMAP_Password($p){
         $this->iMap_Password = $p;
     }