Index: /trunk/include/dblayer/functions_mysqli.inc.php
===================================================================
--- /trunk/include/dblayer/functions_mysqli.inc.php	(revision 27336)
+++ /trunk/include/dblayer/functions_mysqli.inc.php	(revision 27337)
@@ -22,4 +22,8 @@
 // +-----------------------------------------------------------------------+
 
+/**
+ * @package functions\mysql
+ */
+
 define('DB_ENGINE', 'MySQL');
 define('REQUIRED_MYSQL_VERSION', '5.0.0');
@@ -28,19 +32,21 @@
 define('DB_RANDOM_FUNCTION', 'RAND');
 
-/**
- *
- * simple functions
- *
- */
-
+
+/**
+ * Connect to database and store MySQLi resource in __$mysqli__ global variable.
+ *
+ * @param string $host
+ *    - localhost
+ *    - 1.2.3.4:3405
+ *    - /path/to/socket
+ * @param string $user
+ * @param string $password
+ * @param string $database
+ *
+ * @throws Exception
+ */
 function pwg_db_connect($host, $user, $password, $database)
 {
   global $mysqli;
-
-  // $host can be:
-  //
-  // $host = localhost
-  // $host = 1.2.3.4:3405
-  // $host = /path/to/socket
 
   $port = null;
@@ -70,4 +76,7 @@
 }
 
+/**
+ * Set charset for database connection.
+ */
 function pwg_db_check_charset() 
 {
@@ -80,4 +89,7 @@
 }
 
+/**
+ * Check MySQL version. Can call fatal_error().
+ */
 function pwg_db_check_version()
 {
@@ -95,4 +107,9 @@
 }
 
+/**
+ * Get Mysql Version.
+ *
+ * @return string
+ */
 function pwg_get_db_version() 
 {
@@ -102,4 +119,10 @@
 }
 
+/**
+ * Execute a query
+ *
+ * @param string $query
+ * @return mysqli_result|bool
+ */
 function pwg_query($query)
 {
@@ -150,4 +173,11 @@
 }
 
+/**
+ * Get max value plus one of a particular column.
+ *
+ * @param string $column
+ * @param string $table
+ * @param int
+ */
 function pwg_db_nextval($column, $table)
 {
@@ -232,34 +262,33 @@
 }
 
-/**
- *
- * complex functions
- *
- */
 
 define('MASS_UPDATES_SKIP_EMPTY', 1);
-/**
- * updates multiple lines in a table
- *
- * @param string table_name
- * @param array dbfields
- * @param array datas
- * @param int flags - if MASS_UPDATES_SKIP_EMPTY - empty values do not overwrite existing ones
- * @return void
+
+/**
+ * Updates multiple lines in a table.
+ *
+ * @param string $tablename
+ * @param array $dbfields - contains 'primary' and 'update' arrays
+ * @param array $datas - indexed by column names
+ * @param int $flags - if MASS_UPDATES_SKIP_EMPTY, empty values do not overwrite existing ones
  */
 function mass_updates($tablename, $dbfields, $datas, $flags=0)
 {
   if (count($datas) == 0)
+  {
     return;
-  
-  // depending on the MySQL version, we use the multi table update or N update queries
+  }
+
+  // we use the multi table update or N update queries
   if (count($datas) < 10)
   {
     foreach ($datas as $data)
     {
+      $is_first = true;
+
       $query = '
 UPDATE '.$tablename.'
   SET ';
-      $is_first = true;
+
       foreach ($dbfields['update'] as $key)
       {
@@ -272,15 +301,19 @@
         else
         {
-          if ( $flags & MASS_UPDATES_SKIP_EMPTY )
+          if ($flags & MASS_UPDATES_SKIP_EMPTY)
+          {
             continue; // next field
+          }
           $query.= "$separator$key = NULL";
         }
         $is_first = false;
       }
+
       if (!$is_first)
       {// only if one field at least updated
+        $is_first = true;
+
         $query.= '
   WHERE ';
-        $is_first = true;
         foreach ($dbfields['primary'] as $key)
         {
@@ -289,5 +322,5 @@
             $query.= ' AND ';
           }
-          if ( isset($data[$key]) )
+          if (isset($data[$key]))
           {
             $query.= $key.' = \''.$data[$key].'\'';
@@ -299,16 +332,16 @@
           $is_first = false;
         }
+
         pwg_query($query);
       }
     } // foreach update
-  } // if mysqli_ver or count<X
+  } // if count<X
   else
   {
     // creation of the temporary table
-    $query = '
-SHOW FULL COLUMNS FROM '.$tablename;
-    $result = pwg_query($query);
+    $result = pwg_query('SHOW FULL COLUMNS FROM '.$tablename);
     $columns = array();
     $all_fields = array_merge($dbfields['primary'], $dbfields['update']);
+
     while ($row = pwg_db_fetch_assoc($result))
     {
@@ -351,10 +384,11 @@
     pwg_query($query);
     mass_inserts($temporary_tablename, $all_fields, $datas);
-    if ( $flags & MASS_UPDATES_SKIP_EMPTY )
+
+    if ($flags & MASS_UPDATES_SKIP_EMPTY)
       $func_set = create_function('$s', 'return "t1.$s = IFNULL(t2.$s, t1.$s)";');
     else
       $func_set = create_function('$s', 'return "t1.$s = t2.$s";');
 
-    // update of images table by joining with temporary table
+    // update of table by joining with temporary table
     $query = '
 UPDATE '.$tablename.' AS t1, '.$temporary_tablename.' AS t2
@@ -373,31 +407,31 @@
         );
     pwg_query($query);
-    $query = '
-DROP TABLE '.$temporary_tablename;
-    pwg_query($query);
-  }
-}
-
-/**
- * updates one line in a table
- *
- * @param string table_name
- * @param array set_fields
- * @param array where_fields
- * @param int flags - if MASS_UPDATES_SKIP_EMPTY - empty values do not overwrite existing ones
- * @return void
- */
-function single_update($tablename, $set_fields, $where_fields, $flags=0)
-{
-  if (count($set_fields) == 0)
+
+    pwg_query('DROP TABLE '.$temporary_tablename);
+  }
+}
+
+/**
+ * Updates one line in a table.
+ *
+ * @param string $tablename
+ * @param array $datas
+ * @param array $where
+ * @param int $flags - if MASS_UPDATES_SKIP_EMPTY, empty values do not overwrite existing ones
+ */
+function single_update($tablename, $datas, $where, $flags=0)
+{
+  if (count($datas) == 0)
   {
     return;
   }
+
+  $is_first = true;
 
   $query = '
 UPDATE '.$tablename.'
   SET ';
-  $is_first = true;
-  foreach ($set_fields as $key => $value)
+
+  foreach ($datas as $key => $value)
   {
     $separator = $is_first ? '' : ",\n    ";
@@ -409,16 +443,21 @@
     else
     {
-      if ( $flags & MASS_UPDATES_SKIP_EMPTY )
+      if ($flags & MASS_UPDATES_SKIP_EMPTY)
+      {
         continue; // next field
+      }
       $query.= "$separator$key = NULL";
     }
     $is_first = false;
   }
+
   if (!$is_first)
   {// only if one field at least updated
+    $is_first = true;
+
     $query.= '
   WHERE ';
-    $is_first = true;
-    foreach ($where_fields as $key => $value)
+
+    foreach ($where as $key => $value)
     {
       if (!$is_first)
@@ -426,5 +465,5 @@
         $query.= ' AND ';
       }
-      if ( isset($value) )
+      if (isset($value))
       {
         $query.= $key.' = \''.$value.'\'';
@@ -436,16 +475,17 @@
       $is_first = false;
     }
+
     pwg_query($query);
   }
 }
 
-
-/**
- * inserts multiple lines in a table
- *
- * @param string table_name
- * @param array dbfields
- * @param array inserts
- * @return void
+/**
+ * Inserts multiple lines in a table.
+ *
+ * @param string $table_name
+ * @param array $dbfields - fields from $datas which will be used
+ * @param array $datas
+ * @param array $options
+ *    - boolean ignore - use "INSERT IGNORE"
  */
 function mass_inserts($table_name, $dbfields, $datas, $options=array())
@@ -507,4 +547,5 @@
       $query .= ')';
     }
+
     pwg_query($query);
   }
@@ -512,10 +553,8 @@
 
 /**
- * inserts one line in a table
- *
- * @param string table_name
- * @param array dbfields
- * @param array insert
- * @return void
+ * Inserts one line in a table.
+ *
+ * @param string $table_name
+ * @param array $data
  */
 function single_insert($table_name, $data)
@@ -556,8 +595,7 @@
 }
 
-/**
- * Do maintenance on all PWG tables
- *
- * @return none
+
+/**
+ * Do maintenance on all Piwigo tables
  */
 function do_maintenance_all_tables()
@@ -632,22 +670,18 @@
 
 /**
- * returns an array containing the possible values of an enum field
- *
- * @param string tablename
- * @param string fieldname
+ * Returns an array containing the possible values of an enum field.
+ *
+ * @param string $table
+ * @param string $field
+ * @return string[]
  */
 function get_enums($table, $field)
 {
-  // retrieving the properties of the table. Each line represents a field :
-  // columns are 'Field', 'Type'
-  $result = pwg_query('desc '.$table);
+  $result = pwg_query('DESC '.$table);
   while ($row = pwg_db_fetch_assoc($result))
   {
-    // we are only interested in the the field given in parameter for the
-    // function
     if ($row['Field'] == $field)
     {
-      // retrieving possible values of the enum field
-      // enum('blue','green','black')
+      // parse enum('blue','green','black')
       $options = explode(',', substr($row['Type'], 5, -1));
       foreach ($options as $i => $option)
@@ -657,4 +691,5 @@
     }
   }
+
   pwg_db_free_result($result);
   return $options;
@@ -662,7 +697,7 @@
 
 /**
- * Smartly checks if a variable is equivalent to true or false
- *
- * @param mixed input
+ * Checks if a variable is equivalent to true or false.
+ *
+ * @param mixed $input
  * @return bool
  */
@@ -678,5 +713,6 @@
 
 /**
- * returns boolean string 'true' or 'false' if the given var is boolean
+ * Returns string 'true' or 'false' if the given var is boolean.
+ * If the input is another type, it is not changed.
  *
  * @param mixed $var
@@ -694,10 +730,4 @@
   }
 }
-
-/**
- *
- * interval and date functions 
- *
- */
 
 function pwg_db_get_recent_period_expression($period, $date='CURRENT_DATE')
@@ -722,10 +752,10 @@
 function pwg_db_get_flood_period_expression($seconds)
 {
-  return 'SUBDATE(now(), INTERVAL '.$seconds.' SECOND)';
+  return 'SUBDATE(NOW(), INTERVAL '.$seconds.' SECOND)';
 }
 
 function pwg_db_get_hour($date) 
 {
-  return 'hour('.$date.')';
+  return 'HOUR('.$date.')';
 }
 
@@ -782,6 +812,8 @@
 }
 
-// my_error returns (or send to standard output) the message concerning the
-// error occured for the last mysql query.
+/**
+ * Returns (or send to standard output) the message concerning the 
+ * error occured for the last mysql query.
+ */
 function my_error($header, $die)
 {
