feature 2999 : documentation of include/functions.inc.php

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

1 files changed, 272 insertions, 151 deletions

diff --git a/include/functions.inc.php b/include/functions.inc.php
index 8996df05b..18511a6be 100644
--- a/include/functions.inc.php
+++ b/include/functions.inc.php
@@ -1,4 +1,4 @@
-<?php
+<?php 
 // +-----------------------------------------------------------------------+
 // | Piwigo - a PHP based photo gallery                                    |
 // +-----------------------------------------------------------------------+
@@ -21,6 +21,10 @@
 // | USA.                                                                  |
 // +-----------------------------------------------------------------------+
 
+/**
+ * @package functions\___
+ */
+
 include_once( PHPWG_ROOT_PATH .'include/functions_plugins.inc.php' );
 include_once( PHPWG_ROOT_PATH .'include/functions_user.inc.php' );
 include_once( PHPWG_ROOT_PATH .'include/functions_cookie.inc.php' );
@@ -36,10 +40,11 @@ include_once( PHPWG_ROOT_PATH .'include/derivative.inc.php');
 require_once( PHPWG_ROOT_PATH .'include/smarty/libs/SmartyBC.class.php');
 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()
 {
@@ -49,30 +54,49 @@ function micro_seconds()
   return $t2;
 }
 
-// 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()
 {
   return microtime(true);
 }
 
-// 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 )
+/**
+ * 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';
+  return number_format($end - $start, 3, '.', ' ').' s';
 }
 
-// get_extension returns the part of the string after the last "."
+/**
+ * returns the part of the string after the last "."
+ *
+ * @param string $filename
+ * @return string
+ */
 function get_extension( $filename )
 {
   return substr( strrchr( $filename, '.' ), 1, strlen ( $filename ) );
 }
 
-// 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 )
 {
   $pos = strrpos( $filename, '.' );
@@ -86,11 +110,11 @@ define('MKGETDIR_PROTECT_INDEX', 4);
 define('MKGETDIR_PROTECT_HTACCESS', 8);
 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)
 {
@@ -128,11 +152,17 @@ function mkgetdir($dir, $flags=MKGETDIR_DEFAULT)
   return true;
 }
 
-/* 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;
     if ((ord($Str[$i]) & 0xE0) == 0xC0) $n=1; # 110bbbbb
@@ -141,7 +171,8 @@ function qualify_utf8($Str)
     elseif ((ord($Str[$i]) & 0xFC) == 0xF8) $n=4; # 111110bb
     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;
     }
@@ -149,16 +180,22 @@ function qualify_utf8($Str)
   return $ret;
 }
 
-/* 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)
 {
   $utf = qualify_utf8($string);
   if ( $utf == 0 )
+  {
     return $string; // ascii
+  }
 
-  if ( $utf > 0 ) {
+  if ( $utf > 0 )
+  {
     $chars = array(
     // Decompositions for Latin-1 Supplement
     "\xc3\x80"=>'A', "\xc3\x81"=>'A',
@@ -262,7 +299,9 @@ function remove_accents($string)
     "\xc2\xa3"=>'');
 
     $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)
       .chr(159).chr(162).chr(165).chr(181).chr(192).chr(193).chr(194)
@@ -288,6 +327,12 @@ function remove_accents($string)
 
 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)
   {
     return remove_accents( mb_strtolower($term, PWG_CHARSET) );
@@ -295,18 +340,19 @@ if (function_exists('mb_strtolower') && defined('PWG_CHARSET'))
 }
 else
 {
+  /**
+   * @ignore
+   */
   function transliterate($term)
   {
     return remove_accents( strtolower($term) );
   }
 }
 
-
-
 /**
  * simplify a string to insert it into an URL
  *
- * @param string
+ * @param string $str
  * @return string
  */
 function str2url($str)
@@ -324,12 +370,10 @@ function str2url($str)
   return $res;
 }
 
-//-------------------------------------------- Piwigo specific functions
-
 /**
  * returns an array with a list of {language_code => language_name}
  *
- * @returns array
+ * @return string[]
  */
 function get_languages()
 {
@@ -352,6 +396,13 @@ SELECT id, name
   return $languages;
 }
 
+/**
+ * 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)
 {
   global $conf, $user, $page;
@@ -411,13 +462,13 @@ INSERT INTO '.HISTORY_TABLE.'
 }
 
 /**
- * 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
  *
  * @param DateTime $date1
  * @param DateTime $date2
- * @return DateInterval
+ * @return DateInterval|stdClass
  */
 function dateDiff($date1, $date2)
 {
@@ -481,9 +532,10 @@ function dateDiff($date1, $date2)
 
 /**
  * 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)
 {
@@ -524,12 +576,13 @@ function str2DateTime($original, $format=null)
 }
 
 /**
- * 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)
 {
@@ -566,12 +619,13 @@ function format_date($original, $show_time=false, $show_day_name=true, $format=n
 
 /**
  * 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)
 {
@@ -637,11 +691,12 @@ function time_since($original, $stop='minute', $format=null, $with_text=true, $w
 
 /**
  * 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)
 {
@@ -650,6 +705,11 @@ function transform_date($original, $format_in, $format_out, $default=null)
   return $date->format($format_out);
 }
 
+/**
+ * append a variable to _$debug_ global
+ *
+ * @param string $string
+ */
 function pwg_debug( $string )
 {
   global $debug,$t2,$page;
@@ -665,9 +725,8 @@ function pwg_debug( $string )
 }
 
 /**
- * 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.
  *
  * @param string $url
@@ -688,14 +747,13 @@ function redirect_http( $url )
 }
 
 /**
- * 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
  */
 function redirect_html( $url , $msg = '', $refresh_time = 0)
@@ -739,14 +797,13 @@ function redirect_html( $url , $msg = '', $refresh_time = 0)
 }
 
 /**
- * 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
  */
 function redirect( $url , $msg = '', $refresh_time = 0)
@@ -768,10 +825,10 @@ function redirect( $url , $msg = '', $refresh_time = 0)
 }
 
 /**
- * returns $_SERVER['QUERY_STRING'] whitout keys given in parameters
+ * returns $_SERVER['QUERY_STRING'] whithout keys given in parameters
  *
- * @param array $rejects
- * @param boolean $escape - if true escape & to &amp; (for html)
+ * @param string[] $rejects
+ * @param boolean $escape escape *&* to *&amp;*
  * @returns string
  */
 function get_query_string_diff($rejects=array(), $escape=true)
@@ -790,6 +847,7 @@ function get_query_string_diff($rejects=array(), $escape=true)
 
 /**
  * returns true if the url is absolute (begins with http)
+ *
  * @param string $url
  * @returns boolean
  */
@@ -805,6 +863,9 @@ function url_is_remote($url)
 
 /**
  * returns available themes
+ *
+ * @param bool $show_mobile
+ * @return array
  */
 function get_pwg_themes($show_mobile=false)
 {
@@ -842,6 +903,12 @@ SELECT
   return $themes;
 }
 
+/**
+ * check if a theme is installed (directory exsists)
+ *
+ * @param string $theme_id
+ * @return bool
+ */
 function check_theme_installed($theme_id)
 {
   global $conf;
@@ -849,7 +916,13 @@ function check_theme_installed($theme_id)
   return file_exists($conf['themes_dir'].'/'.$theme_id.'/'.'themeconf.inc.php');
 }
 
-/** 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)
 {
   $pos = strrpos($path, '/');
@@ -859,8 +932,10 @@ function original_to_representative($path, $representative_ext)
 }
 
 /**
- * @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)
 {
@@ -874,10 +949,9 @@ function get_element_path($element_info)
 
 
 /**
- * fill the current user caddie with given elements, if not already in
- * caddie
+ * fill the current user caddie with given elements, if not already in caddie
  *
- * @param array elements_id
+ * @param int[] $elements_id
  */
 function fill_caddie($elements_id)
 {
@@ -909,9 +983,10 @@ SELECT element_id
 }
 
 /**
- * returns the element name from its filename
+ * returns the element name from its filename.
+ * removes file extension and replace underscores by spaces
  *
- * @param string filename
+ * @param string $filename
  * @return string name
  */
 function get_name_from_file($filename)
@@ -920,9 +995,10 @@ function get_name_from_file($filename)
 }
 
 /**
- * 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
  * @return string
@@ -951,14 +1027,14 @@ function l10n($key)
 
 /**
  * returns the printf value for strings including %d
- * return is concorded with decimal value (singular, plural)
+ * returned value is concorded with decimal value (singular, plural)
  *
- * @param singular string key
- * @param plural string key
- * @param decimal value
+ * @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;
 
@@ -966,16 +1042,16 @@ function l10n_dec($singular_fmt_key, $plural_fmt_key, $decimal)
     sprintf(
       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
  */
@@ -992,11 +1068,13 @@ function get_l10n_args($key, $args='')
   return array('key_args' => $key_arg);
 }
 
-/*
- * returns a string formated with l10n elements
+/**
+ * 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: l10n_args element or array of l10n_args elements
- * @param string $sep: used when translated elements are concatened
+ * @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
  */
 function l10n_args($key_args, $sep = "\n")
@@ -1034,10 +1112,9 @@ function l10n_args($key_args, $sep = "\n")
 }
 
 /**
- * returns the corresponding value from $themeconf if existing. Else, the
- * key is returned
+ * returns the corresponding value from $themeconf if existing or an empty string
  *
- * @param string key
+ * @param string $key
  * @return string
  */
 function get_themeconf($key)
@@ -1071,6 +1148,7 @@ SELECT '.$conf['user_fields']['email'].'
 /**
  * Add configuration parameters from database to global $conf array
  *
+ * @param string $condition SQL condition
  * @return void
  */
 function load_conf_from_db($condition = '')
@@ -1109,6 +1187,7 @@ SELECT param, value
 
 /**
  * Add or update a config parameter
+ *
  * @param string $param
  * @param string $value
  */
@@ -1145,8 +1224,9 @@ UPDATE '.CONFIG_TABLE.'
 }
 
 /**
- * Delete on or more config parameters
+ * Delete one or more config parameters
  * @since 2.6
+ *
  * @param string|string[] $params
  */
 function conf_delete_param($params)
@@ -1175,11 +1255,12 @@ DELETE FROM '.CONFIG_TABLE.'
 }
 
 /**
- * Prepends and appends a string at each value of the given array.
+ * Prepends and appends strings at each value of the given array.
  *
- * @param array
- * @param string prefix to each array values
- * @param string suffix to each array values
+ * @param array $array
+ * @param string $prepend_str
+ * @param string $append_str
+ * @return array
  */
 function prepend_append_array_items($array, $prepend_str, $append_str)
 {
@@ -1192,9 +1273,8 @@ function prepend_append_array_items($array, $prepend_str, $append_str)
 }
 
 /**
- * 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
  * @param string $keyname
@@ -1215,9 +1295,8 @@ function simple_hash_from_query($query, $keyname, $valuename)
 }
 
 /**
- * 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
  * @param string $keyname
@@ -1235,13 +1314,10 @@ function hash_from_query($query, $keyname)
 }
 
 /**
- * Return basename of the current script
- * Lower case convertion is applied on return value
- * Return value is without file extention ".php"
+ * Return the basename of the current script.
+ * The lowercase case filename of the current script without extension
  *
- * @param void
- *
- * @return script basename
+ * @return string
  */
 function script_basename()
 {
@@ -1265,12 +1341,10 @@ function script_basename()
 }
 
 /**
- * Return value for the current page define on $conf['filter_pages']
- * Îf value is not defined, default value are returned
+ * Return $conf['filter_pages'] value for the current page
  *
- * @param value name
- *
- * @return filter page value
+ * @param string $value_name
+ * @return mixed
  */
 function get_filter_page_value($value_name)
 {
@@ -1293,7 +1367,8 @@ function get_filter_page_value($value_name)
 }
 
 /**
- * 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()
 {
@@ -1306,10 +1381,12 @@ function get_pwg_charset()
 }
 
 /**
- * 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)
 {
@@ -1332,24 +1409,20 @@ function get_parent_language($lang_id=null)
 
 /**
  * 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
+ *     @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() )
+function load_language($filename, $dirname = '', $options = array())
 {
   global $user, $language_files;
   
@@ -1483,9 +1556,10 @@ function load_language($filename, $dirname = '',
 
 /**
  * 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)
 {
@@ -1507,13 +1581,13 @@ function convert_charset($str, $source_charset, $dest_charset)
   {
     return mb_convert_encoding( $str, $dest_charset, $source_charset );
   }
-  return $str; //???
+  return $str; // TODO
 }
 
 /**
  * makes sure a index.htm protects the directory from browser file listing
  *
- * @param string dir directory
+ * @param string $dir
  */
 function secure_directory($dir)
 {
@@ -1527,7 +1601,9 @@ function secure_directory($dir)
 /**
  * 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 = '')
 {
@@ -1540,6 +1616,13 @@ function get_ephemeral_key($valid_after_seconds, $aditionnal_data_to_hash = '')
 			$conf['secret_key']);
 }
 
+/**
+ * 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 = '')
 {
 	global $conf;
@@ -1560,6 +1643,14 @@ function verify_ephemeral_key($key, $aditionnal_data_to_hash = '')
 
 /**
  * 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')
 {
@@ -1616,6 +1707,10 @@ function create_navigation_bar($url, $nb_element, $start, $nb_element_page, $cle
 
 /**
  * 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)
 {
@@ -1656,7 +1751,7 @@ function get_icon($date, $is_child_date = false)
 }
 
 /**
- * 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
  *
@@ -1672,9 +1767,16 @@ function check_pwg_token()
     }
   }
   else
+  {
     bad_request('missing token');
+  }
 }
 
+/**
+ * get pwg_token used to prevent csrf attacks
+ *
+ * @return string
+ */
 function get_pwg_token()
 {
   global $conf;
@@ -1686,13 +1788,11 @@ function get_pwg_token()
  * breaks the script execution if the given value doesn't match the given
  * 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)
 {
@@ -1736,7 +1836,11 @@ function check_input_parameter($param_name, $param_array, $is_array, $pattern, $
   }
 }
 
-
+/**
+ * get localized privacy level values
+ *
+ * @return string[]
+ */
 function get_privacy_level_options()
 {
   global $conf;
@@ -1765,6 +1869,9 @@ function get_privacy_level_options()
 
 /**
  * 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)
 {
@@ -1773,6 +1880,8 @@ function get_branch_from_version($version)
 
 /**
  * return the device type: mobile, tablet or desktop
+ *
+ * @return string
  */
 function get_device()
 {
@@ -1802,6 +1911,8 @@ function get_device()
 
 /**
  * return true if mobile theme should be loaded
+ *
+ * @return bool
  */
 function mobile_theme()
 {
@@ -1833,6 +1944,9 @@ function mobile_theme()
 
 /**
  * check url format
+ *
+ * @param string $url
+ * @return bool
  */
 function url_check_format($url)
 {
@@ -1849,6 +1963,9 @@ function url_check_format($url)
 
 /**
  * check email format
+ *
+ * @param string $mail_address
+ * @return bool
  */
 function email_check_format($mail_address)
 {
@@ -1866,7 +1983,11 @@ function email_check_format($mail_address)
   }
 }
 
-/** 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()
 {
   global $user;