feature 2999: documentation of functions_rate and functions_session

git-svn-id: http://piwigo.org/svn/trunk@25614 68402e56-0260-453c-a942-63ccdbb3a9ee

2 files changed, 94 insertions, 67 deletions

diff --git a/include/functions_rate.inc.php b/include/functions_rate.inc.php
index d0319bd5c..bfac30c75 100644
--- a/include/functions_rate.inc.php
+++ b/include/functions_rate.inc.php
@@ -22,11 +22,16 @@
 // +-----------------------------------------------------------------------+
 
 /**
- * rate a picture by a user
+ * @package functions\rate
+ */
+
+
+/**
+ * Rate a picture by the current user.
  *
- * @param int image identifier
- * @param int rate
- * @return void
+ * @param int $image_id
+ * @param float $rate
+ * @return array as return by update_rating_score()
  */
 function rate_picture($image_id, $rate)
 {
@@ -120,13 +125,14 @@ INSERT
 }
 
 
-/* update images.rating_score field
-  * we use a bayesian average (http://en.wikipedia.org/wiki/Bayesian_average) with
-C = average number of rates per item
-m = global average rate (all rates)
-
- * param int $element_id optional, otherwise applies to all
- * @return array(rating_score, count) if element_id is specified
+/**
+ * Update images.rating_score field.
+ * We use a bayesian average (http://en.wikipedia.org/wiki/Bayesian_average) with
+ *  C = average number of rates per item
+ *  m = global average rate (all rates)
+ *
+ * @param int|false $element_id if false applies to all
+ * @return array (score, average, count) values are null if $element_id is false
 */
 function update_rating_score($element_id = false)
 {
diff --git a/include/functions_session.inc.php b/include/functions_session.inc.php
index 213fceb21..d08655ccc 100644
--- a/include/functions_session.inc.php
+++ b/include/functions_session.inc.php
@@ -21,62 +21,74 @@
 // | USA.                                                                  |
 // +-----------------------------------------------------------------------+
 
-// The function generate_key creates a string with pseudo random characters.
-// the size of the string depends on the $conf['session_id_size'].
-// Characters used are a-z A-Z and numerical values. Examples :
-//                    "Er4Tgh6", "Rrp08P", "54gj"
-// input  : none (using global variable)
-// output : $key
-function generate_key($size)
-{
-  global $conf;
+/**
+ * @package functions\session
+ */
 
-  $md5 = md5(substr(microtime(), 2, 6));
-  $init = '';
-  for ( $i = 0; $i < strlen( $md5 ); $i++ )
-  {
-    if ( is_numeric( $md5[$i] ) ) $init.= $md5[$i];
-  }
-  $init = substr( $init, 0, 8 );
-  mt_srand( $init );
-  $key = '';
-  for ( $i = 0; $i < $size; $i++ )
-  {
-    $c = mt_rand( 0, 2 );
-    if ( $c == 0 )      $key .= chr( mt_rand( 65, 90 ) );
-    else if ( $c == 1 ) $key .= chr( mt_rand( 97, 122 ) );
-    else                $key .= mt_rand( 0, 9 );
-  }
-  return $key;
-}
 
 if (isset($conf['session_save_handler'])
   and ($conf['session_save_handler'] == 'db')
   and defined('PHPWG_INSTALLED'))
 {
-  session_set_save_handler('pwg_session_open',
+  session_set_save_handler(
+    'pwg_session_open',
     'pwg_session_close',
     'pwg_session_read',
     'pwg_session_write',
     'pwg_session_destroy',
     'pwg_session_gc'
   );
-  if ( function_exists('ini_set') )
+
+  if (function_exists('ini_set'))
   {
     ini_set('session.use_cookies', $conf['session_use_cookies']);
     ini_set('session.use_only_cookies', $conf['session_use_only_cookies']);
     ini_set('session.use_trans_sid', intval($conf['session_use_trans_sid']));
     ini_set('session.cookie_httponly', 1);
   }
+
   session_name($conf['session_name']);
   session_set_cookie_params(0, cookie_path());
   register_shutdown_function('session_write_close');
 }
 
+
+/**
+ * Generates a pseudo random string.
+ * Characters used are a-z A-Z and numerical values.
+ *
+ * @param int $size
+ * @return string
+ */
+function generate_key($size)
+{
+  global $conf;
+
+  $md5 = md5(substr(microtime(), 2, 6));
+  $init = '';
+  for ( $i = 0; $i < strlen( $md5 ); $i++ )
+  {
+    if ( is_numeric( $md5[$i] ) ) $init.= $md5[$i];
+  }
+  $init = substr( $init, 0, 8 );
+  mt_srand( $init );
+  $key = '';
+  for ( $i = 0; $i < $size; $i++ )
+  {
+    $c = mt_rand( 0, 2 );
+    if ( $c == 0 )      $key .= chr( mt_rand( 65, 90 ) );
+    else if ( $c == 1 ) $key .= chr( mt_rand( 97, 122 ) );
+    else                $key .= mt_rand( 0, 9 );
+  }
+  return $key;
+}
+
 /**
- * returns true; used when the session_start() function is called
+ * Called by PHP session manager, always return true.
  *
- * @params not use but useful for php engine
+ * @param string $path
+ * @param sring $name
+ * @return true
  */
 function pwg_session_open($path, $name)
 {
@@ -84,14 +96,20 @@ function pwg_session_open($path, $name)
 }
 
 /**
- * returns true; used when the session is closed (unset($_SESSION))
+ * Called by PHP session manager, always return true.
  *
+ * @return true
  */
 function pwg_session_close()
 {
   return true;
 }
 
+/**
+ * Returns a hash from current user IP
+ *
+ * @return string
+ */
 function get_remote_addr_session_hash()
 {
   global $conf;
@@ -112,11 +130,10 @@ function get_remote_addr_session_hash()
 }
 
 /**
- * this function returns
- * a string corresponding to the value of the variable save in the session
- * or an empty string when the variable doesn't exist
+ * Called by PHP session manager, retrieves data stored in the sessions table.
  *
- * @param string session id
+ * @param string $session_id
+ * @return string
  */
 function pwg_session_read($session_id)
 {
@@ -138,10 +155,11 @@ SELECT data
 }
 
 /**
- * returns true; writes set a variable in the active session
+ * Called by PHP session manager, writes data in the sessions table.
  *
- * @param string session id
- * @data string value of date to be saved
+ * @param string $session_id
+ * @param sring $data
+ * @return true
  */
 function pwg_session_write($session_id, $data)
 {
@@ -155,9 +173,10 @@ REPLACE INTO '.SESSIONS_TABLE.'
 }
 
 /**
- * returns true; delete the active session
+ * Called by PHP session manager, deletes data in the sessions table.
  *
- * @param string session id
+ * @param string $session_id
+ * @return true
  */
 function pwg_session_destroy($session_id)
 {
@@ -171,8 +190,9 @@ DELETE
 }
 
 /**
- * returns true; delete expired sessions
- * called each time a session is closed.
+ * Called by PHP session manager, garbage collector for expired sessions.
+ *
+ * @return true
  */
 function pwg_session_gc()
 {
@@ -188,12 +208,12 @@ DELETE
   return true;
 }
 
-
 /**
- * persistently stores a variable for the current session
- * currently we use standard php sessions but it might change
- * @return boolean true on success
- * @see pwg_get_session_var, pwg_unset_session_var
+ * Persistently stores a variable for the current session.
+ *
+ * @param string $var
+ * @param mixed $value
+ * @return bool
  */
 function pwg_set_session_var($var, $value)
 {
@@ -204,10 +224,11 @@ function pwg_set_session_var($var, $value)
 }
 
 /**
- * retrieves the value of a persistent variable for the current session
- * currently we use standard php sessions but it might change
+ * Retrieves the value of a persistent variable for the current session.
+ *
+ * @param string $var
+ * @param mixed $default
  * @return mixed
- * @see pwg_set_session_var, pwg_unset_session_var
  */
 function pwg_get_session_var($var, $default = null)
 {
@@ -219,10 +240,10 @@ function pwg_get_session_var($var, $default = null)
 }
 
 /**
- * deletes a persistent variable for the current session
- * currently we use standard php sessions but it might change
- * @return boolean true on success
- * @see pwg_set_session_var, pwg_get_session_var
+ * Deletes a persistent variable for the current session.
+ *
+ * @param string $var
+ * @return bool
  */
 function pwg_unset_session_var($var)
 {
@@ -232,4 +253,4 @@ function pwg_unset_session_var($var)
   return true;
 }
 
-?>
+?>
\ No newline at end of file