Index: /trunk/include/functions.inc.php
===================================================================
--- /trunk/include/functions.inc.php	(revision 25425)
+++ /trunk/include/functions.inc.php	(revision 25426)
@@ -1,3 +1,3 @@
-<?php
+<?php 
 // +-----------------------------------------------------------------------+
 // | Piwigo - a PHP based photo gallery                                    |
@@ -22,4 +22,8 @@
 // +-----------------------------------------------------------------------+
 
+/**
+ * @package functions\___
+ */
+
 include_once( PHPWG_ROOT_PATH .'include/functions_plugins.inc.php' );
 include_once( PHPWG_ROOT_PATH .'include/functions_user.inc.php' );
@@ -37,8 +41,9 @@
 include_once( PHPWG_ROOT_PATH .'include/template.class.php');
 
-//----------------------------------------------------------- generic functions
-
-/**
- * stupidly returns the current microsecond since Unix epoch
+
+/**
+ * returns the current microsecond since Unix epoch
+ *
+ * @return int
  */
 function micro_seconds()
@@ -50,7 +55,11 @@
 }
 
-// The function get_moment returns a float value coresponding to the number
-// of seconds since the unix epoch (1st January 1970) and the microseconds
-// are precised : e.g. 1052343429.89276600
+/**
+ * returns a float value coresponding to the number of seconds since
+ * the unix epoch (1st January 1970) and the microseconds are precised
+ * e.g. 1052343429.89276600
+ *
+ * @return float
+ */
 function get_moment()
 {
@@ -58,12 +67,23 @@
 }
 
-// The function get_elapsed_time returns the number of seconds (with 3
-// decimals precision) between the start time and the end time given.
-function get_elapsed_time( $start, $end )
-{
-  return number_format( $end - $start, 3, '.', ' ').' s';
-}
-
-// get_extension returns the part of the string after the last "."
+/**
+ * returns the number of seconds (with 3 decimals precision)
+ * between the start time and the end time given
+ *
+ * @param float $start
+ * @param float $end
+ * @return string "$TIME s"
+ */
+function get_elapsed_time($start, $end)
+{
+  return number_format($end - $start, 3, '.', ' ').' s';
+}
+
+/**
+ * returns the part of the string after the last "."
+ *
+ * @param string $filename
+ * @return string
+ */
 function get_extension( $filename )
 {
@@ -71,7 +91,11 @@
 }
 
-// get_filename_wo_extension returns the part of the string before the last
-// ".".
-// get_filename_wo_extension( 'test.tar.gz' ) -> 'test.tar'
+/**
+ * returns the part of the string before the last ".".
+ * get_filename_wo_extension( 'test.tar.gz' ) = 'test.tar'
+ *
+ * @param string $filename
+ * @return string
+ */
 function get_filename_wo_extension( $filename )
 {
@@ -87,9 +111,9 @@
 define('MKGETDIR_DEFAULT', 7);
 /**
- * creates directory if not exists; ensures that directory is writable
- * @param:
- *  string $dir
- *  int $flags combination of MKGETDIR_xxx
- * @return bool false on error else true
+ * creates directory if not exists and ensures that directory is writable
+ *
+ * @param string $dir
+ * @param int $flags combination of MKGETDIR_xxx
+ * @return bool
  */
 function mkgetdir($dir, $flags=MKGETDIR_DEFAULT)
@@ -129,9 +153,15 @@
 }
 
-/* returns 0 if $str is Ascii, 1 if utf-8, -1 otherwise */
+/**
+ * finds out if a string is in ASCII, UTF-8 or other encoding
+ *
+ * @param string $str
+ * @return int *0* if _$str_ is ASCII, *1* if UTF-8, *-1* otherwise
+ */
 function qualify_utf8($Str)
 {
   $ret = 0;
-  for ($i=0; $i<strlen($Str); $i++) {
+  for ($i=0; $i<strlen($Str); $i++)
+  {
     if (ord($Str[$i]) < 0x80) continue; # 0bbbbbbb
     $ret = 1;
@@ -142,5 +172,6 @@
     elseif ((ord($Str[$i]) & 0xFE) == 0xFC) $n=5; # 1111110b
     else return -1; # Does not match any model
-    for ($j=0; $j<$n; $j++) { # n bytes matching 10bbbbbb follow ?
+    for ($j=0; $j<$n; $j++)
+    { # n bytes matching 10bbbbbb follow ?
       if ((++$i == strlen($Str)) || ((ord($Str[$i]) & 0xC0) != 0x80))
         return -1;
@@ -150,6 +181,9 @@
 }
 
-/* Remove accents from a UTF-8 or ISO-859-1 string (from wordpress)
- * @param string sstring - an UTF-8 or ISO-8859-1 string
+/**
+ * Remove accents from a UTF-8 or ISO-8859-1 string (from wordpress)
+ *
+ * @param string $string
+ * @return string
  */
 function remove_accents($string)
@@ -157,7 +191,10 @@
   $utf = qualify_utf8($string);
   if ( $utf == 0 )
+  {
     return $string; // ascii
-
-  if ( $utf > 0 ) {
+  }
+
+  if ( $utf > 0 )
+  {
     $chars = array(
     // Decompositions for Latin-1 Supplement
@@ -263,5 +300,7 @@
 
     $string = strtr($string, $chars);
-  } else {
+  }
+  else
+  {
     // Assume ISO-8859-1 if not UTF-8
     $chars['in'] = chr(128).chr(131).chr(138).chr(142).chr(154).chr(158)
@@ -289,4 +328,10 @@
 if (function_exists('mb_strtolower') && defined('PWG_CHARSET'))
 {
+  /**
+   * removes accents from a string and converts it to lower case
+   *
+   * @param string $term
+   * @return string
+   */
   function transliterate($term)
   {
@@ -296,4 +341,7 @@
 else
 {
+  /**
+   * @ignore
+   */
   function transliterate($term)
   {
@@ -302,10 +350,8 @@
 }
 
-
-
 /**
  * simplify a string to insert it into an URL
  *
- * @param string
+ * @param string $str
  * @return string
  */
@@ -325,10 +371,8 @@
 }
 
-//-------------------------------------------- Piwigo specific functions
-
 /**
  * returns an array with a list of {language_code => language_name}
  *
- * @returns array
+ * @return string[]
  */
 function get_languages()
@@ -353,4 +397,11 @@
 }
 
+/**
+ * log the visit into history table
+ *
+ * @param int $image_id
+ * @param string $image_type
+ * @return bool
+ */
 function pwg_log($image_id = null, $image_type = null)
 {
@@ -412,5 +463,5 @@
 
 /**
- * Computes the difference between two dates
+ * Computes the difference between two dates.
  * returns a DateInterval object or a stdClass with the same attributes
  * http://stephenharris.info/date-intervals-in-php-5-2
@@ -418,5 +469,5 @@
  * @param DateTime $date1
  * @param DateTime $date2
- * @return DateInterval
+ * @return DateInterval|stdClass
  */
 function dateDiff($date1, $date2)
@@ -482,7 +533,8 @@
 /**
  * converts a string into a DateTime object
- * @param: mixed, datetime string or timestamp int
- * @param: string, input format
- * @return: DateTime or false
+ *
+ * @param int|string timestamp or datetime string
+ * @param string $format input format respecting date() syntax
+ * @return DateTime|false
  */
 function str2DateTime($original, $format=null)
@@ -525,10 +577,11 @@
 
 /**
- * returns a formatted date for display
- * @param: mixed, datetime string or timestamp int
- * @param: bool, show time
- * @param: bool, show day name
- * @param: string, input format
- * @return: string
+ * returns a formatted and localized date for display
+ *
+ * @param int|string timestamp or datetime string
+ * @param bool $show_time
+ * @param bool $show_day_name
+ * @param string $format input format respecting date() syntax
+ * @return string
  */
 function format_date($original, $show_time=false, $show_day_name=true, $format=null)
@@ -567,10 +620,11 @@
 /**
  * Works out the time since the given date
- * @param: mixed, datetime string or timestamp int
- * @param: string, stop (year,month,week,day,hour,minute,second)
- * @param: string, input format
- * @param: bool, append text ("ago" or "in the future")
- * @param: bool, display weeks
- * @return: string
+ *
+ * @param int|string timestamp or datetime string
+ * @param string $stop year,month,week,day,hour,minute,second
+ * @param string $format input format respecting date() syntax
+ * @param bool $with_text append "ago" or "in the future"
+ * @param bool $with_weeks
+ * @return string
  */
 function time_since($original, $stop='minute', $format=null, $with_text=true, $with_week=true)
@@ -638,9 +692,10 @@
 /**
  * transform a date string from a format to another (MySQL to d/M/Y for instance)
- * @param: string, date
- * @param: string, input format
- * @param: string, output format
- * @param: string, default value if inout is empty
- * @return: string
+ *
+ * @param string $original
+ * @param string $format_in respecting date() syntax
+ * @param string $format_out respecting date() syntax
+ * @param string $default if _$original_ is empty
+ * @return string
  */
 function transform_date($original, $format_in, $format_out, $default=null)
@@ -651,4 +706,9 @@
 }
 
+/**
+ * append a variable to _$debug_ global
+ *
+ * @param string $string
+ */
 function pwg_debug( $string )
 {
@@ -666,7 +726,6 @@
 
 /**
- * Redirects to the given URL (HTTP method)
- *
- * Note : once this function called, the execution doesn't go further
+ * Redirects to the given URL (HTTP method).
+ * once this function called, the execution doesn't go further
  * (presence of an exit() instruction.
  *
@@ -689,12 +748,11 @@
 
 /**
- * Redirects to the given URL (HTML method)
- *
- * Note : once this function called, the execution doesn't go further
+ * Redirects to the given URL (HTML method).
+ * once this function called, the execution doesn't go further
  * (presence of an exit() instruction.
  *
  * @param string $url
- * @param string $title_msg
- * @param integer $refreh_time
+ * @param string $msg
+ * @param integer $refresh_time
  * @return void
  */
@@ -740,12 +798,11 @@
 
 /**
- * Redirects to the given URL (Switch to HTTP method or HTML method)
- *
- * Note : once this function called, the execution doesn't go further
+ * Redirects to the given URL (automatically choose HTTP or HTML method).
+ * once this function called, the execution doesn't go further
  * (presence of an exit() instruction.
  *
  * @param string $url
- * @param string $title_msg
- * @param integer $refreh_time
+ * @param string $msg
+ * @param integer $refresh_time
  * @return void
  */
@@ -769,8 +826,8 @@
 
 /**
- * returns $_SERVER['QUERY_STRING'] whitout keys given in parameters
- *
- * @param array $rejects
- * @param boolean $escape - if true escape & to &amp; (for html)
+ * returns $_SERVER['QUERY_STRING'] whithout keys given in parameters
+ *
+ * @param string[] $rejects
+ * @param boolean $escape escape *&* to *&amp;*
  * @returns string
  */
@@ -791,4 +848,5 @@
 /**
  * returns true if the url is absolute (begins with http)
+ *
  * @param string $url
  * @returns boolean
@@ -806,4 +864,7 @@
 /**
  * returns available themes
+ *
+ * @param bool $show_mobile
+ * @return array
  */
 function get_pwg_themes($show_mobile=false)
@@ -843,4 +904,10 @@
 }
 
+/**
+ * check if a theme is installed (directory exsists)
+ *
+ * @param string $theme_id
+ * @return bool
+ */
 function check_theme_installed($theme_id)
 {
@@ -850,5 +917,11 @@
 }
 
-/** Transforms an original path to its pwg representative */
+/**
+ * Transforms an original path to its pwg representative
+ *
+ * @param string $path
+ * @param string $representative_ext
+ * @return string
+ */
 function original_to_representative($path, $representative_ext)
 {
@@ -860,6 +933,8 @@
 
 /**
- * @param element_info array containing element information from db;
- * at least 'id', 'path' should be present
+ * get the full path of an image
+ *
+ * @param array $element_info element information from db (at least 'path')
+ * @return strinf
  */
 function get_element_path($element_info)
@@ -875,8 +950,7 @@
 
 /**
- * fill the current user caddie with given elements, if not already in
- * caddie
- *
- * @param array elements_id
+ * fill the current user caddie with given elements, if not already in caddie
+ *
+ * @param int[] $elements_id
  */
 function fill_caddie($elements_id)
@@ -910,7 +984,8 @@
 
 /**
- * returns the element name from its filename
- *
- * @param string filename
+ * returns the element name from its filename.
+ * removes file extension and replace underscores by spaces
+ *
+ * @param string $filename
  * @return string name
  */
@@ -921,7 +996,8 @@
 
 /**
- * translation function
- * returns the corresponding value from $lang if existing, else the key is returned
+ * translation function.
+ * returns the corresponding value from _$lang_ if existing else the key is returned
  * if more than one parameter is provided sprintf is applied
+ *
  * @param string $key
  * @param mixed $args,... optional arguments
@@ -952,12 +1028,12 @@
 /**
  * returns the printf value for strings including %d
- * return is concorded with decimal value (singular, plural)
- *
- * @param singular string key
- * @param plural string key
- * @param decimal value
+ * returned value is concorded with decimal value (singular, plural)
+ *
+ * @param string $singular_key
+ * @param string $plural_key
+ * @param int $decimal
  * @return string
  */
-function l10n_dec($singular_fmt_key, $plural_fmt_key, $decimal)
+function l10n_dec($singular_key, $plural_key, $decimal)
 {
   global $lang_info;
@@ -967,14 +1043,14 @@
       l10n((
         (($decimal > 1) or ($decimal == 0 and $lang_info['zero_plural']))
-          ? $plural_fmt_key
-          : $singular_fmt_key
+          ? $plural_key
+          : $singular_key
         )), $decimal);
 }
 
-/*
+/**
  * returns a single element to use with l10n_args
  *
- * @param string key: translation key
- * @param mixed args: arguments to use on sprintf($key, args)
+ * @param string $key translation key
+ * @param mixed $args arguments to use on sprintf($key, args)
  *   if args is a array, each values are used on sprintf
  * @return string
@@ -993,9 +1069,11 @@
 }
 
-/*
- * returns a string formated with l10n elements
- *
- * @param array $key_args: l10n_args element or array of l10n_args elements
- * @param string $sep: used when translated elements are concatened
+/**
+ * returns a string formated with l10n elements.
+ * it is usefull to "prepare" a text and translate it later
+ * @see get_l10n_args() 
+ *
+ * @param array $key_args one l10n_args element or array of l10n_args elements
+ * @param string $sep used when translated elements are concatened
  * @return string
  */
@@ -1035,8 +1113,7 @@
 
 /**
- * returns the corresponding value from $themeconf if existing. Else, the
- * key is returned
- *
- * @param string key
+ * returns the corresponding value from $themeconf if existing or an empty string
+ *
+ * @param string $key
  * @return string
  */
@@ -1072,4 +1149,5 @@
  * Add configuration parameters from database to global $conf array
  *
+ * @param string $condition SQL condition
  * @return void
  */
@@ -1110,4 +1188,5 @@
 /**
  * Add or update a config parameter
+ *
  * @param string $param
  * @param string $value
@@ -1146,6 +1225,7 @@
 
 /**
- * Delete on or more config parameters
+ * Delete one or more config parameters
  * @since 2.6
+ *
  * @param string|string[] $params
  */
@@ -1176,9 +1256,10 @@
 
 /**
- * Prepends and appends a string at each value of the given array.
- *
- * @param array
- * @param string prefix to each array values
- * @param string suffix to each array values
+ * Prepends and appends strings at each value of the given array.
+ *
+ * @param array $array
+ * @param string $prepend_str
+ * @param string $append_str
+ * @return array
  */
 function prepend_append_array_items($array, $prepend_str, $append_str)
@@ -1193,7 +1274,6 @@
 
 /**
- * creates an hashed based on a query, this function is a very common
- * pattern used here. Among the selected columns fetched, choose one to be
- * the key, another one to be the value.
+ * creates an simple hashmap based on a SQL query.
+ * choose one to be the key, another one to be the value.
  *
  * @param string $query
@@ -1216,7 +1296,6 @@
 
 /**
- * creates an hashed based on a query, this function is a very common
- * pattern used here. The key is given as parameter, the value is an associative
- * array.
+ * creates an associative array based on a SQL query.
+ * choose one to be the key
  *
  * @param string $query
@@ -1236,11 +1315,8 @@
 
 /**
- * Return basename of the current script
- * Lower case convertion is applied on return value
- * Return value is without file extention ".php"
- *
- * @param void
- *
- * @return script basename
+ * Return the basename of the current script.
+ * The lowercase case filename of the current script without extension
+ *
+ * @return string
  */
 function script_basename()
@@ -1266,10 +1342,8 @@
 
 /**
- * Return value for the current page define on $conf['filter_pages']
- * Îf value is not defined, default value are returned
- *
- * @param value name
- *
- * @return filter page value
+ * Return $conf['filter_pages'] value for the current page
+ *
+ * @param string $value_name
+ * @return mixed
  */
 function get_filter_page_value($value_name)
@@ -1294,5 +1368,6 @@
 
 /**
- * returns the character set of data sent to browsers / received from forms
+ * return the character set used by Piwigo
+ * @return string
  */
 function get_pwg_charset()
@@ -1307,8 +1382,10 @@
 
 /**
- * returns the parent language of the current language or any language
+ * returns the parent (fallback) language of a language.
+ * if _$lang_id_ is null it applies to the current language
  * @since 2.6
+ *
  * @param string $lang_id
- * @return string
+ * @return string|null
  */
 function get_parent_language($lang_id=null)
@@ -1333,22 +1410,18 @@
 /**
  * includes a language file or returns the content of a language file
- * availability of the file
- *
- * in descending order of preference:
+ *
+ * tries to load in descending order:
  *   param language, user language, default language
- * Piwigo default language.
- *
- * @param string filename
- * @param string dirname
+ *
+ * @param string $filename
+ * @param string $dirname
  * @param mixed options can contain
- *     language - language to load (if empty uses user language)
- *     return - if true the file content is returned otherwise the file is evaluated as php
- *     target_charset -
- *     no_fallback - the language must be respected
- *     local - if true, get local language file
- * @return boolean success status or a string if options['return'] is true
- */
-function load_language($filename, $dirname = '',
-    $options = array() )
+ *     @option string language - language to load
+ *     @option bool return - if true the file content is returned
+ *     @option bool no_fallback - if true do not load default language
+ *     @option bool local - if true load file from local directory
+ * @return boolean|string
+ */
+function load_language($filename, $dirname = '', $options = array())
 {
   global $user, $language_files;
@@ -1484,7 +1557,8 @@
 /**
  * converts a string from a character set to another character set
- * @param string str the string to be converted
- * @param string source_charset the character set in which the string is encoded
- * @param string dest_charset the destination character set
+ *
+ * @param string $str
+ * @param string $source_charset
+ * @param string $dest_charset
  */
 function convert_charset($str, $source_charset, $dest_charset)
@@ -1508,5 +1582,5 @@
     return mb_convert_encoding( $str, $dest_charset, $source_charset );
   }
-  return $str; //???
+  return $str; // TODO
 }
 
@@ -1514,5 +1588,5 @@
  * makes sure a index.htm protects the directory from browser file listing
  *
- * @param string dir directory
+ * @param string $dir
  */
 function secure_directory($dir)
@@ -1528,5 +1602,7 @@
  * returns a "secret key" that is to be sent back when a user posts a form
  *
- * @param int valid_after_seconds - key validity start time from now
+ * @param int $valid_after_seconds - key validity start time from now
+ * @param string $aditionnal_data_to_hash
+ * @return string
  */
 function get_ephemeral_key($valid_after_seconds, $aditionnal_data_to_hash = '')
@@ -1541,4 +1617,11 @@
 }
 
+/**
+ * verify a key sent back with a form
+ *
+ * @param string $key
+ * @param string $aditionnal_data_to_hash
+ * @return bool
+ */
 function verify_ephemeral_key($key, $aditionnal_data_to_hash = '')
 {
@@ -1561,4 +1644,12 @@
 /**
  * return an array which will be sent to template to display navigation bar
+ *
+ * @param string $url base url of all links
+ * @param int $nb_elements
+ * @param int $start
+ * @param int $nb_element_page
+ * @param bool $clean_url
+ * @param string $param_name
+ * @return array
  */
 function create_navigation_bar($url, $nb_element, $start, $nb_element_page, $clean_url = false, $param_name='start')
@@ -1617,4 +1708,8 @@
 /**
  * return an array which will be sent to template to display recent icon
+ *
+ * @param string $date
+ * @param bool $is_child_date
+ * @return array
  */
 function get_icon($date, $is_child_date = false)
@@ -1657,5 +1752,5 @@
 
 /**
- * check token comming from form posted or get params to prevent csrf attacks
+ * check token comming from form posted or get params to prevent csrf attacks.
  * if pwg_token is empty action doesn't require token
  * else pwg_token is compare to server token
@@ -1673,7 +1768,14 @@
   }
   else
+  {
     bad_request('missing token');
-}
-
+  }
+}
+
+/**
+ * get pwg_token used to prevent csrf attacks
+ *
+ * @return string
+ */
 function get_pwg_token()
 {
@@ -1687,11 +1789,9 @@
  * pattern. This should happen only during hacking attempts.
  *
- * @param string param_name
- * @param array param_array
- * @param boolean is_array
- * @param string pattern
- * @param boolean mandatory
- *
- * @return void
+ * @param string $param_name
+ * @param array $param_array
+ * @param boolean $is_array
+ * @param string $pattern
+ * @param boolean $mandatory
  */
 function check_input_parameter($param_name, $param_array, $is_array, $pattern, $mandatory=false)
@@ -1737,5 +1837,9 @@
 }
 
-
+/**
+ * get localized privacy level values
+ *
+ * @return string[]
+ */
 function get_privacy_level_options()
 {
@@ -1766,4 +1870,7 @@
 /**
  * return the branch from the version. For example version 2.2.4 is for branch 2.2
+ *
+ * @param string $version
+ * @return string
  */
 function get_branch_from_version($version)
@@ -1774,4 +1881,6 @@
 /**
  * return the device type: mobile, tablet or desktop
+ *
+ * @return string
  */
 function get_device()
@@ -1803,4 +1912,6 @@
 /**
  * return true if mobile theme should be loaded
+ *
+ * @return bool
  */
 function mobile_theme()
@@ -1834,4 +1945,7 @@
 /**
  * check url format
+ *
+ * @param string $url
+ * @return bool
  */
 function url_check_format($url)
@@ -1850,4 +1964,7 @@
 /**
  * check email format
+ *
+ * @param string $mail_address
+ * @return bool
  */
 function email_check_format($mail_address)
@@ -1867,5 +1984,9 @@
 }
 
-/** returns the number of available comments for the connected user */
+/**
+ * returns the number of available comments for the connected user
+ *
+ * @return int
+ */
 function get_nb_available_comments()
 {
