Index: /trunk/include/functions_category.inc.php
===================================================================
--- /trunk/include/functions_category.inc.php	(revision 25657)
+++ /trunk/include/functions_category.inc.php	(revision 25658)
@@ -343,5 +343,5 @@
  *
  * @param string[] $permalinks
- * @param int $idx filled with the index in $permalinks that matches
+ * @param int &$idx filled with the index in $permalinks that matches
  * @return int|null
  */
Index: /trunk/include/functions_comment.inc.php
===================================================================
--- /trunk/include/functions_comment.inc.php	(revision 25657)
+++ /trunk/include/functions_comment.inc.php	(revision 25658)
@@ -73,7 +73,7 @@
  * Tries to insert a user comment and returns action to perform.
  *
- * @param array $comm
+ * @param array &$comm
  * @param string $key secret key sent back to the browser
- * @param array $infos output array of error messages
+ * @param array &$infos output array of error messages
  * @return string validate, moderate, reject
  */
Index: /trunk/include/functions_filter.inc.php
===================================================================
--- /trunk/include/functions_filter.inc.php	(revision 25657)
+++ /trunk/include/functions_filter.inc.php	(revision 25658)
@@ -30,5 +30,5 @@
  * Updates data of categories with filtered values
  *
- * @param array $cats
+ * @param array &$cats
  */
 function update_cats_with_filtered_data(&$cats)
Index: /trunk/include/functions_notification.inc.php
===================================================================
--- /trunk/include/functions_notification.inc.php	(revision 25657)
+++ /trunk/include/functions_notification.inc.php	(revision 25658)
@@ -362,5 +362,5 @@
  * Formats a news line and adds it to the array (e.g. '5 new elements')
  *
- * @param array $news
+ * @param array &$news
  * @param int $count
  * @param string $singular_key
Index: /trunk/include/functions_plugins.inc.php
===================================================================
--- /trunk/include/functions_plugins.inc.php	(revision 25657)
+++ /trunk/include/functions_plugins.inc.php	(revision 25658)
@@ -51,5 +51,5 @@
   /**
    * @param string $plugin_version
-   * @param array $errors - used to return error messages
+   * @param array &$errors - used to return error messages
    */
   abstract function install($plugin_version, &$errors=array());
@@ -57,5 +57,5 @@
   /**
    * @param string $plugin_version
-   * @param array $errors - used to return error messages
+   * @param array &$errors - used to return error messages
    */
   abstract function activate($plugin_version, &$errors=array());
@@ -120,5 +120,5 @@
   /**
    * @param string $theme_version
-   * @param array $errors - used to return error messages
+   * @param array &$errors - used to return error messages
    */
   abstract function activate($theme_version, &$errors=array());
@@ -343,5 +343,5 @@
  *
  * @param string $plugin_id
- * @param mixed $data
+ * @param mixed &$data
  * @return bool
  */
Index: /trunk/include/functions_search.inc.php
===================================================================
--- /trunk/include/functions_search.inc.php	(revision 25657)
+++ /trunk/include/functions_search.inc.php	(revision 25658)
@@ -22,10 +22,14 @@
 // +-----------------------------------------------------------------------+
 
-
-/**
- * returns search rules stored into a serialized array in "search"
+/**
+ * @package functions\search
+ */
+
+
+/**
+ * Returns search rules stored into a serialized array in "search"
  * table. Each search rules set is numericaly identified.
  *
- * @param int search_id
+ * @param int $search_id
  * @return array
  */
@@ -48,10 +52,8 @@
 
 /**
- * returns the SQL clause from a search identifier
- *
- * Search rules are stored in search table as a serialized array. This array
- * need to be transformed into an SQL clause to be used in queries.
- *
- * @param array search
+ * Returns the SQL clause for a search.
+ * Transforms the array returned by get_search_array() into SQL sub-query.
+ *
+ * @param array $search
  * @return string
  */
@@ -171,10 +173,11 @@
 
 /**
- * returns the list of items corresponding to the advanced search array
- *
- * @param array search
+ * Returns the list of items corresponding to the advanced search array.
+ *
+ * @param array $search
+ * @param string $images_where optional additional restriction on images table
  * @return array
  */
-function get_regular_search_results($search, $images_where)
+function get_regular_search_results($search, $images_where='')
 {
   global $conf;
@@ -247,5 +250,10 @@
 }
 
-
+/**
+ * Finds if a char is a letter, a figure or any char of the extended ASCII table (>127).
+ *
+ * @param char $ch
+ * @return bool
+ */
 function is_word_char($ch)
 {
@@ -253,4 +261,10 @@
 }
 
+/**
+ * Finds if a char is a special token for word start: [{<=*+
+ *
+ * @param char $ch
+ * @return bool
+ */
 function is_odd_wbreak_begin($ch)
 {
@@ -258,4 +272,10 @@
 }
 
+/**
+ * Finds if a char is a special token for word end: ]}>=*+
+ *
+ * @param char $ch
+ * @return bool
+ */
 function is_odd_wbreak_end($ch)
 {
@@ -263,16 +283,20 @@
 }
 
-define('QST_QUOTED',   0x01);
-define('QST_NOT',      0x02);
-define('QST_WILDCARD_BEGIN',0x04);
-define('QST_WILDCARD_END',  0x08);
+
+define('QST_QUOTED',         0x01);
+define('QST_NOT',            0x02);
+define('QST_WILDCARD_BEGIN', 0x04);
+define('QST_WILDCARD_END',   0x08);
 define('QST_WILDCARD', QST_WILDCARD_BEGIN|QST_WILDCARD_END);
 
-
-/**
- * analyzes and splits the quick/query search query $q into tokens
+/**
+ * Analyzes and splits the quick/query search query $q into tokens.
  * q='john bill' => 2 tokens 'john' 'bill'
  * Special characters for MySql full text search (+,<,>,~) appear in the token modifiers.
  * The query can contain a phrase: 'Pierre "New York"' will return 'pierre' qnd 'new york'.
+ *
+ * @param string $q
+ * @param array &$qtokens
+ * @param array &$qtoken_modifiers
  */
 function analyse_qsearch($q, &$qtokens, &$qtoken_modifiers)
@@ -369,9 +393,13 @@
 }
 
-
-/**
- * returns the LIKE sql clause corresponding to the quick search query
- * that has been split into tokens
+/**
+ * Returns the LIKE SQL clause corresponding to the quick search query
+ * that has been split into tokens.
  * for example file LIKE '%john%' OR file LIKE '%bill%'.
+ *
+ * @param array $tokens
+ * @param array $token_modifiers
+ * @param string $field
+ * @return string|null
  */
 function get_qsearch_like_clause($tokens, $token_modifiers, $field)
@@ -394,5 +422,12 @@
 
 /**
-*/
+ * Returns tags corresponding to the quick search query that has been split into tokens.
+ *
+ * @param array $tokens
+ * @param array $token_modifiers
+ * @param array &$token_tag_ids
+ * @param array &$not_tag_ids
+ * @param array &$all_tags
+ */
 function get_qsearch_tags($tokens, $token_modifiers, &$token_tag_ids, &$not_tag_ids, &$all_tags)
 {
@@ -547,22 +582,25 @@
   usort($all_tags, 'tag_alpha_compare');
   foreach ( $all_tags as &$tag )
+  {
     $tag['name'] = trigger_event('render_tag_name', $tag['name']);
-}
-
-/**
- * returns the search results corresponding to a quick/query search.
+  }
+}
+
+/**
+ * Returns the search results corresponding to a quick/query search.
  * A quick/query search returns many items (search is not strict), but results
  * are sorted by relevance unless $super_order_by is true. Returns:
- * array (
- * 'items' => array(85,68,79...)
- * 'qs'    => array(
- *    'matching_tags' => array of matching tags
- *    'matching_cats' => array of matching categories
- *    'matching_cats_no_images' =>array(99) - matching categories without images
- *      ))
- *
- * @param string q
- * @param bool super_order_by
- * @param string images_where optional aditional restriction on images table
+ *  array (
+ *    'items' => array of matching images
+ *    'qs'    => array(
+ *      'matching_tags' => array of matching tags
+ *      'matching_cats' => array of matching categories
+ *      'matching_cats_no_images' =>array(99) - matching categories without images
+ *      )
+ *    )
+ *
+ * @param string $q
+ * @param bool $super_order_by
+ * @param string $images_where optional additional restriction on images table
  * @return array
  */
@@ -764,8 +802,10 @@
 
 /**
- * returns an array of 'items' corresponding to the search id
- *
- * @param int search id
- * @param string images_where optional aditional restriction on images table
+ * Returns an array of 'items' corresponding to the search id.
+ * It can be either a quick search or a regular search.
+ *
+ * @param int $search_id
+ * @param bool $super_order_by
+ * @param string $images_where optional aditional restriction on images table
  * @return array
  */
@@ -783,3 +823,4 @@
   }
 }
+
 ?>
Index: /trunk/include/functions_tag.inc.php
===================================================================
--- /trunk/include/functions_tag.inc.php	(revision 25657)
+++ /trunk/include/functions_tag.inc.php	(revision 25658)
@@ -22,6 +22,14 @@
 // +-----------------------------------------------------------------------+
 
-
-/** returns the number of available tags for the connected user */
+/**
+ * @package functions\tag
+ */
+
+
+/**
+ * Returns the number of available tags for the connected user.
+ *
+ * @return int
+ */
 function get_nb_available_tags()
 {
@@ -39,12 +47,9 @@
 
 /**
- * Tags available. Each return tag is represented as an array with its id,
- * its name, its weight (count), its url name. Tags are not sorted.
- *
- * The returned list can be a subset of all existing tags due to
- * permissions, only if a list of forbidden categories is provided
- *
- * @param array forbidden categories
- * @return array
+ * Returns all available tags for the connected user (not sorted).
+ * The returned list can be a subset of all existing tags due to permissions,
+ * also tags with no images are not returned.
+ *
+ * @return array [id, name, counter, url_name]
  */
 function get_available_tags()
@@ -54,16 +59,16 @@
 SELECT tag_id, COUNT(DISTINCT(it.image_id)) AS counter
   FROM '.IMAGE_CATEGORY_TABLE.' ic
-    INNER JOIN '.IMAGE_TAG_TABLE.' it ON ic.image_id=it.image_id'.get_sql_condition_FandF
-    (
-      array
-        (
-          'forbidden_categories' => 'category_id',
-          'visible_categories' => 'category_id',
-          'visible_images' => 'ic.image_id'
-        ),
-      '
-  WHERE'
+    INNER JOIN '.IMAGE_TAG_TABLE.' it
+    ON ic.image_id=it.image_id
+  '.get_sql_condition_FandF(
+    array(
+      'forbidden_categories' => 'category_id',
+      'visible_categories' => 'category_id',
+      'visible_images' => 'ic.image_id'
+      ),
+    ' WHERE '
     ).'
-  GROUP BY tag_id';
+  GROUP BY tag_id
+;';
   $tag_counters = simple_hash_from_query($query, 'tag_id', 'counter');
 
@@ -77,4 +82,5 @@
   FROM '.TAGS_TABLE;
   $result = pwg_query($query);
+
   $tags = array();
   while ($row = pwg_db_fetch_assoc($result))
@@ -92,7 +98,7 @@
 
 /**
- * All tags, even tags associated to no image.
- *
- * @return array
+ * Returns all tags even associated to no image.
+ *
+ * @return array [id, name, url_name]
  */
 function get_all_tags()
@@ -120,9 +126,9 @@
  *
  * The level of each tag depends on the average count of tags. This
- * calcylation method avoid having very different levels for tags having
+ * calculation method avoid having very different levels for tags having
  * nearly the same count when set are small.
  *
- * @param array tags
- * @return array
+ * @param array $tags at least [id, counter]
+ * @return array [..., level]
  */
 function add_level_to_tags($tags)
@@ -174,11 +180,12 @@
 
 /**
- * return the list of image ids corresponding to given tags. AND & OR mode
- * supported.
- *
- * @param array tag ids
+ * Return the list of image ids corresponding to given tags.
+ * AND & OR mode supported.
+ *
+ * @param int[] $tag_ids
  * @param string mode
- * @param string extra_images_where_sql - optionally apply a sql where filter to retrieved images
- * @param string order_by - optionally overwrite default photo order
+ * @param string $extra_images_where_sql - optionally apply a sql where filter to retrieved images
+ * @param string $order_by - optionally overwrite default photo order
+ * @param bool $user_permissions
  * @return array
  */
@@ -191,5 +198,6 @@
   }
 
-  $query = 'SELECT id
+  $query = '
+SELECT id
   FROM '.IMAGES_TABLE.' i ';
 
@@ -230,12 +238,12 @@
 
 /**
- * return a list of tags corresponding to given items.
- *
- * @param array items
- * @param array max_tags
- * @param array excluded_tag_ids
- * @return array
- */
-function get_common_tags($items, $max_tags, $excluded_tag_ids=null)
+ * Return a list of tags corresponding to given items.
+ *
+ * @param int[] $items
+ * @param int $max_tags
+ * @param int[] $excluded_tag_ids
+ * @return array [id, name, counter, url_name]
+ */
+function get_common_tags($items, $max_tags, $excluded_tag_ids=array())
 {
   if (empty($items))
@@ -257,5 +265,5 @@
   ORDER BY ';
   if ($max_tags>0)
-  {
+  { // TODO : why ORDER field is in the if ?
     $query .= 'counter DESC
   LIMIT '.$max_tags;
@@ -278,43 +286,27 @@
 
 /**
- * return a list of tags corresponding to any of ids, url_names, names
- *
- * @param array ids
- * @param array url_names
- * @param array names
- * @return array
- */
-function find_tags($ids, $url_names=array(), $names=array() )
+ * Return a list of tags corresponding to any of ids, url_names or names.
+ *
+ * @param int[] $ids
+ * @param string[] $url_names
+ * @param string[] $names
+ * @return array [id, name, url_name]
+ */
+function find_tags($ids=array(), $url_names=array(), $names=array() )
 {
   $where_clauses = array();
-  if ( !empty($ids) )
+  if (!empty($ids))
   {
     $where_clauses[] = 'id IN ('.implode(',', $ids).')';
   }
-  if ( !empty($url_names) )
+  if (!empty($url_names))
   {
     $where_clauses[] =
-      'url_name IN ('.
-      implode(
-        ',',
-        array_map(
-          create_function('$s', 'return "\'".$s."\'";'),
-          $url_names
-          )
-        )
-      .')';
-  }
-  if ( !empty($names) )
+      'url_name IN (\''. implode('\', \'', $url_names) .'\')';
+  }
+  if (!empty($names))
   {
     $where_clauses[] =
-      'name IN ('.
-      implode(
-        ',',
-        array_map(
-          create_function('$s', 'return "\'".$s."\'";'),
-          $names
-          )
-        )
-      .')';
+      'name IN (\''. implode('\', \'', $names) .'\')';
   }
   if (empty($where_clauses))
@@ -337,3 +329,4 @@
   return $tags;
 }
+
 ?>
