From 77d9dd967f4ca22c1f1774f718c312e32c2eb07f Mon Sep 17 00:00:00 2001
From: shubham_meena <shubham.iit17@gmail.com>
Date: Mon, 18 Aug 2014 07:13:15 +0530
Subject: [PATCH] Improved documentation with doxygen generated doc

---
 code/web/private_php/ams/autoload/dblayer.php | 97 ++++++++++++-------
 .../private_php/ams/autoload/plugincache.php  | 26 +++--
 .../web/private_php/ams/autoload/rest_api.php |  8 +-
 .../private_php/ams/autoload/ticket_log.php   |  2 +-
 .../ams/plugins/API_key_management/.info      |  2 +-
 .../public_php/ams/func/activate_plugin.php   |  8 +-
 .../public_php/ams/func/deactivate_plugin.php | 10 +-
 .../web/public_php/ams/func/delete_plugin.php |  8 +-
 .../public_php/ams/func/install_plugin.php    | 41 ++++++--
 .../web/public_php/ams/func/update_plugin.php |  6 +-
 .../web/public_php/ams/inc/plugins_update.php |  2 +-
 11 files changed, 146 insertions(+), 64 deletions(-)

diff --git a/code/web/private_php/ams/autoload/dblayer.php b/code/web/private_php/ams/autoload/dblayer.php
index 43282789e..7c4c5435c 100644
--- a/code/web/private_php/ams/autoload/dblayer.php
+++ b/code/web/private_php/ams/autoload/dblayer.php
@@ -3,13 +3,36 @@
  * 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.
  * 
+ * --> First create an object of dblayer --> $db = new DBLayer('short database name used in config')
+ * 
+ * --> Insert -->  $db->insert( $tb_name, $data )
+ * 				   $tb_name = table name in which we want to insert data
+ * 				   $data = array of data that needs to be inserted in format('fieldname' => $value) where fieldname must be a field in that table. 	
+ * 
+ * --> select -->  $db->select( $tb_name, $data, $where )
+ *                 $tb_name = table name which we want to select
+ * 				   $data = array of data which is then required in WHERE clause in format array('fieldname'=>$value) fieldname must be a field in that table.
+ *				   $where = string in format ('fieldname=:fieldname') where :fieldname takes it's value from $data array. 
+ * 
+ * --> update -->  $db->update( $tb_name, $data, $where )
+ * 				   $tb_name = table name which we want to update
+ * 				   $data = array of data which contains the filelds that need to be updated with their values in the format('fieldname' => $value,...) where fieldname must be a field in that table.
+ * 				   $where = string contains the filename with a value at that field in the format ('fieldname = $value') where fieldname must be a field in that table and $value is value respect to that field.		
+ * 
+ * --> delete -->  $db->delete( $tb_name, $data, $where )
+ * 				   $tb_name = table name where we want to delete.
+ * 				   $data = array of data which is then required in WHERE clause in format array('fieldname'=> $value) where fieldname must be a field in that table.	
+ * 				   $where = string in format ('fieldname=:fieldname') where :fieldname takes it's value from $data array.
+ * 
+ * 
  * @author Daan Janssens, mentored by Matthew Lagoe 
+ * 
  */
 class DBLayer {
     
     private $PDO;
     /**
-     * *< The PDO object, instantiated by the constructor
+     *  The PDO object, instantiated by the constructor
      */
     
     /**
@@ -17,6 +40,7 @@ class DBLayer {
      * Instantiates the PDO object attribute by connecting to the arguments matching database(the db info is stored in the $cfg global var)
      * 
      * @param  $db String, the name of the databases entry in the $cfg global var.
+     * @param  $dbn String, the name of the databases entry in the $cfg global var if $db referenced to an action(install etc).
      */
      function __construct( $db, $dbn = null )
      {
@@ -49,10 +73,10 @@ class DBLayer {
         } 
     
     /**
-     * execute a query that doesn't have any parameters
+     * Execute a query that doesn't have any parameters.
      * 
-     * @param  $query the mysql query
-     * @return returns a PDOStatement object
+     * @param  $query the mysql query.
+     * @return returns a PDOStatement object.
      */
     public function executeWithoutParams( $query ) {
         $statement = $this -> PDO -> prepare( $query );
@@ -61,11 +85,11 @@ class DBLayer {
          } 
     
     /**
-     * execute a query that has parameters
+     * 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
+     * @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 );
@@ -74,10 +98,10 @@ class DBLayer {
          } 
     
     /**
-     * execute a query (an insertion query) that has parameters and return the id of it's insertion
+     * Insert function which returns id of the inserting field. 
      * 
-     * @param  $query the mysql query
-     * @param  $params the parameters that are being used by the query
+     * @param  $tb_name table name where we want to insert data.
+     * @param  $data the parameters that are being inserted into table.
      * @return returns the id of the last inserted element.
      */
     public function executeReturnId( $tb_name, $data ) {
@@ -104,12 +128,14 @@ class DBLayer {
          } 
     
     /**
-     * Select function using prepared statement
+     * Select function using prepared statement.
+     * For selecting particular fields.
      * 
-     * @param string $tb_name Table Name to Select
-     * @param array $data Associative array
-     * @param string $where where to select
-     * @return statement object
+     * @param string $param field to select, can be multiple fields.
+     * @param string $tb_name Table Name to Select.
+     * @param array $data array of data to be used in WHERE clause in format('fieldname'=>$value). 'fieldname' must be a field in that table.
+     * @param string $where where to select.
+     * @return statement object.
      */
     public function selectWithParameter( $param, $tb_name, $data, $where )
      {
@@ -129,12 +155,13 @@ class DBLayer {
          } 
     
     /**
-     * Select function using prepared statement
+     * Select function using prepared statement.
+     * For selecting all fields in a table.
      * 
-     * @param string $tb_name Table Name to Select
-     * @param array $data Associative array
-     * @param string $where where to select
-     * @return statement object
+     * @param string $tb_name Table Name to Select.
+     * @param array $data array of data to be used with WHERE part in format('fieldname'=>$value,...). 'fieldname' must be a field in that table.
+     * @param string $where where to select in format('fieldname=:fieldname' AND ...).
+     * @return statement object.
      */
     public function select( $tb_name, $data , $where )
      {
@@ -154,12 +181,12 @@ class DBLayer {
          } 
     
     /**
-     * Update function with prepared statement
+     * Update function with prepared statement.
      * 
-     * @param string $tb_name name of the table
-     * @param array $data associative array with values
-     * @param string $where where part
-     * @throws Exception error in updating
+     * @param string $tb_name name of the table on which operation to be performed.
+     * @param array $data array of data in format('fieldname' => $value,...).Here, only those fields must be stored which needs to be updated.
+     * @param string $where where part in format ('fieldname'= $value AND ...). 'fieldname' must be a field in that table.
+     * @throws Exception error in updating.
      */
     public function update( $tb_name, $data, $where )
      {
@@ -190,10 +217,11 @@ class DBLayer {
          }
  
     /**
-     * insert function using prepared statements
+     * insert function using prepared statements.
      * 
-     * @param string $tb_name Name of the table to insert in
-     * @param array $data Associative array of data to insert
+     * @param string $tb_name Name of the table on which operation to be performed.
+     * @param array $data  array of data to insert in format('fieldname' => $value,....). 'fieldname' must be a field in that table.
+     * @throws error in inserting.
      */
     public function insert( $tb_name, $data )
      {
@@ -216,16 +244,17 @@ class DBLayer {
          {
             // for rolling back the changes during transaction
             $this -> PDO -> rollBack();
-             throw new Exception( "error in inseting" );
+             throw new Exception( "error in inserting" );
              } 
         } 
     
     /**
-     * Delete database entery using prepared statement
+     * Delete database entery using prepared statement.
      * 
-     * @param string $tb_name 
-     * @param string $where 
-     * @throws error in deleting
+     * @param string $tb_name table name on which operations to be performed.
+     * @param $data array with values in the format('fieldname'=> $value,...). 'fieldname' must be a field in that table.  
+     * @param string $where condition based on $data array in the format('fieldname=:fieldname' AND ...).
+     * @throws error in deleting.
      */
     public function delete( $tb_name, $data, $where )
      {
diff --git a/code/web/private_php/ams/autoload/plugincache.php b/code/web/private_php/ams/autoload/plugincache.php
index c90665bc1..8ff258513 100644
--- a/code/web/private_php/ams/autoload/plugincache.php
+++ b/code/web/private_php/ams/autoload/plugincache.php
@@ -2,7 +2,7 @@
 
 /**
  * API for loading and interacting with plugins
- *     contains getters and setters
+ * contains getters and setters.
  * 
  * @author shubham meena mentored by Matthew Lagoe 
  */
@@ -14,11 +14,11 @@ class Plugincache {
      private $plugin_status;
      private $plugin_info = array();
      private $update_info = array();
+    
     /**
      * A constructor.
      * Empty constructor
      */
-    
      public function __construct() {
         } 
     
@@ -207,10 +207,12 @@ class Plugincache {
         } 
     
     /**
-     * returns plugin information with respect to the id
+     * Returns plugin information with respect to the id.
      * 
-     * @param id $ plugin id
-     * @return field info for the plugin
+     * @param $id  plugin id.
+     * @param $fieldName string plugin field to return
+     *  
+     * @return info field from the db.
      */
     public static function pluginInfoUsingId( $id, $fieldName )
      {
@@ -221,9 +223,9 @@ class Plugincache {
          } 
     
     /**
-     * function provides list of active plugins
+     * Function provides list of active plugins
      * 
-     * @return $ac_plugins list of active plugins
+     * @return  list of active plugins
      */
     public static function activePlugins()
      {
@@ -235,9 +237,15 @@ class Plugincache {
     
     /**
      * function to load hooks for the active plugins
-     * and return the contents in the hooks in an array
+     * and return the contents get from them.
      * 
-     * @return $content content available in hooks
+     * -->Get the list of active plugins then call the global
+     *    hooks exists in the plugins hook file ($pluginName.php).
+     * -->Collect the contents from the hooks and associate within 
+     *    array with key referenced plugin name. 
+     * -->return the content to use with smarty template loader   
+     * 
+     * @return $content content get from hooks
      */
     public static function loadHooks()
      {
diff --git a/code/web/private_php/ams/autoload/rest_api.php b/code/web/private_php/ams/autoload/rest_api.php
index 74281c6f6..e35586042 100644
--- a/code/web/private_php/ams/autoload/rest_api.php
+++ b/code/web/private_php/ams/autoload/rest_api.php
@@ -5,7 +5,7 @@
  * 
  * Request for the given url using cURL  
  * and send the AccessToken for authentication 
- * to make public access for the user
+ * to make public access for the user.
  * 
  * @author Shubham Meena, mentored by Matthew Lagoe 
  */
@@ -13,12 +13,14 @@
 class Rest_Api {
     
     /**
-     * Makes a request using cURL with authentication headers and returns the response.
+     * Makes a request using cURL with authentication headers , data to post and returns the response.
      * 
      * @param  $url where request is to be sent
      * @param  $applicationKey user generated key
      * @param  $host host for the website
-     * @return URL response.
+     * @param  $data data to send using POST request
+     * 
+     * @return $response  URL response.
      */
     public function request( $url , $applicationKey, $host , $data )
      {
diff --git a/code/web/private_php/ams/autoload/ticket_log.php b/code/web/private_php/ams/autoload/ticket_log.php
index 6693fe3ce..f83d4b29e 100644
--- a/code/web/private_php/ams/autoload/ticket_log.php
+++ b/code/web/private_php/ams/autoload/ticket_log.php
@@ -143,7 +143,7 @@ class Ticket_Log{
     /**
     * loads the object's attributes.
     * loads the object's attributes by giving a ticket_log entries ID (TLogId).
-    * @param id the id of the ticket_log entry that should be loaded
+    * @param $id the id of the ticket_log entry that should be loaded
     */
     public function load_With_TLogId( $id) {
         $dbl = new DBLayer("lib");
diff --git a/code/web/private_php/ams/plugins/API_key_management/.info b/code/web/private_php/ams/plugins/API_key_management/.info
index b185a31db..1da25516e 100644
--- a/code/web/private_php/ams/plugins/API_key_management/.info
+++ b/code/web/private_php/ams/plugins/API_key_management/.info
@@ -1,7 +1,7 @@
 PluginName = API Key Management
 Description = Provides public access to the API's by generating access tokens. 
 Version = 1.0.0
-Type = automatic
+Type = Manual
 TemplatePath = ../../../ams_lib/plugins/API_key_management/templates/index.tpl
 
 
diff --git a/code/web/public_php/ams/func/activate_plugin.php b/code/web/public_php/ams/func/activate_plugin.php
index 930ed15f1..0a331f284 100644
--- a/code/web/public_php/ams/func/activate_plugin.php
+++ b/code/web/public_php/ams/func/activate_plugin.php
@@ -1,6 +1,9 @@
 <?php
 /**
  * This function is used in activating plugins.
+ * This can be done by providing id using $_GET global variable of the plugin which
+ * we want to activate. After getting id we update the respective plugin with status
+ * activate which here means '1' .
  * 
  * @author Shubham Meena, mentored by Matthew Lagoe 
  */
@@ -11,23 +14,26 @@ function activate_plugin() {
         
         if ( isset( $_GET['id'] ) )
              {
-            // id of plugin to delete
+            // id of plugin to activate
             $id = filter_var( $_GET['id'], FILTER_SANITIZE_FULL_SPECIAL_CHARS );
              $db = new DBLayer( 'lib' );
              $result = $db -> update( "plugins", array( 'Status' => '1' ), "Id = $id" );
              if ( $result )
              {
+				 // if result is successfull it redirects and shows success message
                 header( "Location: index.php?page=plugins&result=3" );
                  exit;
                  } 
             else
                  {
+				//if result is unsuccessfull it redirects and throws error 	 
                 header( "Location: index.php?page=plugins&result=4" );
                  exit;
                  } 
             } 
         else
              {
+			//if $_GET variable is not set it redirects and shows error
             header( "Location: index.php?page=plugins&result=4" );
              exit;
              } 
diff --git a/code/web/public_php/ams/func/deactivate_plugin.php b/code/web/public_php/ams/func/deactivate_plugin.php
index a4b6120b1..91986bb50 100644
--- a/code/web/public_php/ams/func/deactivate_plugin.php
+++ b/code/web/public_php/ams/func/deactivate_plugin.php
@@ -1,6 +1,9 @@
 <?php
 /**
  * This function is used in deactivating plugins.
+ * This can be done by providing id using $_GET global variable of the plugin which
+ * we want to activate. After getting id we update the respective plugin with status
+ * deactivate which here means '0'.
  * 
  * @author Shubham Meena, mentored by Matthew Lagoe 
  */
@@ -12,17 +15,19 @@ function deactivate_plugin() {
         
         if ( isset( $_GET['id'] ) )
              {
-            // id of plugin to delete
+            // id of plugin to deactivate
             $id = filter_var( $_GET['id'], FILTER_SANITIZE_FULL_SPECIAL_CHARS );
              $db = new DBLayer( 'lib' );
              $result = $db -> update( "plugins", array( 'Status' => '0' ), "Id = $id" );
              if ( $result )
-             {
+             {  
+				// if result is successfull it redirects and shows success message 
                 header( "Location: index.php?page=plugins&result=5" );
                  exit;
                  } 
             else
                  {
+				// if result is unsuccessfull it redirects and shows success message	 
                 header( "Location: index.php?page=plugins&result=6" );
                  exit;
                 
@@ -30,6 +35,7 @@ function deactivate_plugin() {
             } 
         else
              {
+			//if $_GET variable is not set it redirects and shows error	 
             header( "Location: index.php?page=plugins&result=6" );
              exit;
              } 
diff --git a/code/web/public_php/ams/func/delete_plugin.php b/code/web/public_php/ams/func/delete_plugin.php
index f3dc0311a..d85ed34b9 100644
--- a/code/web/public_php/ams/func/delete_plugin.php
+++ b/code/web/public_php/ams/func/delete_plugin.php
@@ -1,8 +1,9 @@
 <?php
 /**
  * This function is used in deleting plugins.
- * 
- * It removes the plugin from the codebase.
+ * It removes the plugin from the codebase as well as
+ * from the Database. When user request to delete a plugin
+ * id of that plugin is sent in $_GET global variable. 
  * 
  * @author Shubham Meena, mentored by Matthew Lagoe 
  */
@@ -27,12 +28,14 @@ function delete_plugin() {
                      {
                     $db -> delete( 'plugins', array( 'id' => $id ), "Id=:id" );
                     
+                    //if result	successfull redirect and show success message
                      header( "Location: index.php?page=plugins&result=2" );
                      exit;
                     
                      } 
                 else
                      {
+					// if result unsuccessfull redirect and show error message 
                     header( "Location: index.php?page=plugins&result=0" );
                      exit;
                      } 
@@ -40,6 +43,7 @@ function delete_plugin() {
             } 
         else
              {
+			// if result unsuccessfull redirect and show error message 	 
             header( "Location: index.php?page=plugins&result=0" );
              exit;
              } 
diff --git a/code/web/public_php/ams/func/install_plugin.php b/code/web/public_php/ams/func/install_plugin.php
index 052d4f14b..1ad7154d2 100644
--- a/code/web/public_php/ams/func/install_plugin.php
+++ b/code/web/public_php/ams/func/install_plugin.php
@@ -1,10 +1,32 @@
 <?php
+
 /**
- * This function is used in installing plugins
- * It performs validation check for the compressed plugin
- * then extract in plugin folder to get the info
+ * This module contains the function to install plugins
+ * or check if the uploaded file is an update for a plugin.
+ *  
+ * When user uploads a file with .zip extension(neccessary requirement)
+ * steps that should perform: 
+ * --> Check if the file type is .zip.
+ * --> Extract it to a temp folder. 
+ * --> Check for the .info file. If not exists throw error
+ * --> Extract the information from the .info file.
+ * --> Check for the plugin name already exists or not.
+ * --> if Plugin Name exists it compare the version of .info and version of plugin stored in db.
+ * --> if same throw error and if different it checks for UpdateInfo field in .info file.
+ * --> if UpdateInfo not found throw error.
+ * --> if UpdateInfo found add the update to the ryzom_ams_lib.updates table.
+ * --> if it's not an update and plugin with same name already exists throw error.
+ * --> if plugin with same name not present provide option to install plugin 
+ * 
+ * @author Shubham Meena, mentored by Matthew Lagoe
+ * 
+ */ 
+
+
+/**
+ * This function is used in installing plugins or adding updates
+ * for previously installed plugins.
  * 
- * @author Shubham Meena, mentored by Matthew Lagoe 
  */
 function install_plugin() {
     
@@ -165,13 +187,14 @@ function zipExtraction( $target_path, $destination )
  * PluginName = Name of the plugin 
  * Version = version of the plugin
  * Type = type of the plugin
+ * TemplatePath = path to the template
  * Description = Description of the plugin ,it's functionality
  * -----------------------------------------------------------
  * 
  * reads only files with name .info
  * 
  * @param  $fileName file to read
- * @param  $targetPath path to the folder containing .info file
+ * @param  $target_path path to the folder containing .info file
  * @return array containing above information in array(value => key)
  */
 function readPluginFile( $fileName, $target_path )
@@ -190,8 +213,8 @@ function readPluginFile( $fileName, $target_path )
 /**
  * function to check for updates or 
  * if the same plugin already exists
- * also, if the update founds ,check for the update info in the .info file. 
- * Update is saved in the temp direcotry with pluginName_version.zip
+ * also, if the update founds ,check for the UpdateInfo in the .info file. 
+ * Update is saved in the temp directory with pluginName_version.zip
  * 
  * @param  $fileName file which is uploaded in .zip extension
  * @param  $findPath where we have to look for the installed plugins
@@ -286,8 +309,8 @@ function checkForUpdate( $fileName, $findPath, $tempFile, $tempPath )
  * 
  * @param  $pluginId id of the plugin for which update is available
  * @param  $updatePath path of the new update
- * @return boolean if update for a plugin already exists or 
- *                                      if update of same version is uploading
+ * @return boolean True if update already exists else False 
+ *                                      
  */
 function PluginUpdateExists( $pluginId, $updatePath )
  {
diff --git a/code/web/public_php/ams/func/update_plugin.php b/code/web/public_php/ams/func/update_plugin.php
index 1420572b1..cacc5f119 100644
--- a/code/web/public_php/ams/func/update_plugin.php
+++ b/code/web/public_php/ams/func/update_plugin.php
@@ -1,6 +1,9 @@
 <?php
 /**
  * This function is used in installing updates for plugins.
+ * It takes id of the plugin whose update is available using
+ * $_GET global variable and then extract the update details 
+ * from db and then install it in the plugin.
  * 
  * @author Shubham Meena, mentored by Matthew Lagoe 
  */
@@ -11,7 +14,7 @@ function update_plugin() {
         
         if ( isset( $_GET['id'] ) )
              {
-            // id of plugin to delete
+            // id of plugin to update
             $id = filter_var( $_GET['id'], FILTER_SANITIZE_FULL_SPECIAL_CHARS );
              $db = new DBLayer( 'lib' );
              $sth = $db -> executeWithoutParams( "SELECT * FROM plugins INNER JOIN updates ON plugins.Id=updates.PluginId Where plugins.Id=$id" );
@@ -26,6 +29,7 @@ function update_plugin() {
              // deleting the previous update
             $db -> delete( "updates", array( 'id' => $row['s.no'] ), "s.no=:id" );
           
+             // if update is installed succesffully redirect to show success message
              header( "Location: index.php?page=plugins&result=8" );
              exit;
             
diff --git a/code/web/public_php/ams/inc/plugins_update.php b/code/web/public_php/ams/inc/plugins_update.php
index 89d547860..e08869f98 100644
--- a/code/web/public_php/ams/inc/plugins_update.php
+++ b/code/web/public_php/ams/inc/plugins_update.php
@@ -1,7 +1,7 @@
 <?php
 /**
  * function plugins_update to get
- * plugins updates from the Database using pagination object
+ * plugins updates from the Database using pagination object.
  * 
  * @author shubham meena mentored by Matthew Lagoe 
  */