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

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

1 files changed, 260 insertions, 187 deletions

diff --git a/admin/include/functions.php b/admin/include/functions.php
index ba6cdf40d..71c164822 100644
--- a/admin/include/functions.php
+++ b/admin/include/functions.php
@@ -21,11 +21,19 @@
 // | USA.                                                                  |
 // +-----------------------------------------------------------------------+
 
-include(PHPWG_ROOT_PATH.'admin/include/functions_metadata.php');
+/**
+ * @package functions\admin\___
+ */
+
+include_once(PHPWG_ROOT_PATH.'admin/include/functions_metadata.php');
+
 
-// The function delete_site deletes a site and call the function
-// delete_categories for each primary category of the site
-function delete_site( $id )
+/**
+ * Deletes a site and call delete_categories for each primary category of the site
+ *
+ * @param int $id
+ */
+function delete_site($id)
 {
   // destruction of the categories of the site
   $query = '
@@ -44,18 +52,19 @@ DELETE FROM '.SITES_TABLE.'
   pwg_query($query);
 }
 
-
-// The function delete_categories deletes the categories identified by the
-// (numeric) key of the array $ids. It also deletes (in the database) :
-//    - all the elements physically linked to the category (delete_elements, see further)
-//    - all the links between elements and this category
-//    - all the restrictions linked to the category
-// The function works recursively.
-//
-// the $photo_deletion_mode is for photos virtually linked to the categorty
-//   * no_delete : delete no photo, may create orphans
-//   * delete_orphans : delete photos that are no longer linked to any category
-//   * force_delete : delete photos even if they are linked to another category
+/**
+ * Recursively deletes one or more categories.
+ * It also deletes :
+ *    - all the elements physically linked to the category (with delete_elements)
+ *    - all the links between elements and this category
+ *    - all the restrictions linked to the category
+ *
+ * @param int[] $ids
+ * @param string $photo_deletion_mode
+ *    - no_delete : delete no photo, may create orphans
+ *    - delete_orphans : delete photos that are no longer linked to any category
+ *    - force_delete : delete photos even if they are linked to another category
+ */
 function delete_categories($ids, $photo_deletion_mode='no_delete')
 {
   if (count($ids) == 0)
@@ -156,8 +165,12 @@ DELETE FROM '.USER_CACHE_CATEGORIES_TABLE.'
   trigger_action('delete_categories', $ids);
 }
 
-// Deletes all files (on disk) related to given image ids
-// @return image ids where files are deleted successfully
+/**
+ * Deletes all files (on disk) related to given image ids.
+ *
+ * @param int[] $ids
+ * @return 0|int[] image ids where files were successfully deleted
+ */
 function delete_element_files($ids)
 {
   global $conf;
@@ -219,12 +232,18 @@ SELECT
   return $new_ids;
 }
 
-// The function delete_elements deletes the elements identified by the
-// (numeric) values of the array $ids. It also deletes (in the database) :
-//    - all the comments related to elements
-//    - all the links between categories and elements
-//    - all the favorites associated to elements
-// @return number of deleted elements
+/**
+ * Deletes elements from database.
+ * It also deletes :
+ *    - all the comments related to elements
+ *    - all the links between categories/tags and elements
+ *    - all the favorites/rates associated to elements
+ *    - removes elements from caddie
+ *
+ * @param int[] $ids
+ * @param bool $physical_deletion
+ * @return int number of deleted elements
+ */
 function delete_elements($ids, $physical_deletion=false)
 {
   if (count($ids) == 0)
@@ -241,60 +260,55 @@ function delete_elements($ids, $physical_deletion=false)
       return 0;
     }
   }
+  
+  $ids_str = wordwrap(implode(', ', $ids), 80, "\n");
 
   // destruction of the comments on the image
   $query = '
 DELETE FROM '.COMMENTS_TABLE.'
-  WHERE image_id IN (
-'.wordwrap(implode(', ', $ids), 80, "\n").')
+  WHERE image_id IN ('. $ids_str .')
 ;';
   pwg_query($query);
 
-  // destruction of the links between images and this category
+  // destruction of the links between images and categories
   $query = '
 DELETE FROM '.IMAGE_CATEGORY_TABLE.'
-  WHERE image_id IN (
-'.wordwrap(implode(', ', $ids), 80, "\n").')
+  WHERE image_id IN ('. $ids_str .')
 ;';
   pwg_query($query);
 
   // destruction of the links between images and tags
   $query = '
 DELETE FROM '.IMAGE_TAG_TABLE.'
-  WHERE image_id IN (
-'.wordwrap(implode(', ', $ids), 80, "\n").')
+  WHERE image_id IN ('. $ids_str .')
 ;';
   pwg_query($query);
 
   // destruction of the favorites associated with the picture
   $query = '
 DELETE FROM '.FAVORITES_TABLE.'
-  WHERE image_id IN (
-'.wordwrap(implode(', ', $ids), 80, "\n").')
+  WHERE image_id IN ('. $ids_str .')
 ;';
   pwg_query($query);
 
   // destruction of the rates associated to this element
   $query = '
 DELETE FROM '.RATE_TABLE.'
-  WHERE element_id IN (
-'.wordwrap(implode(', ', $ids), 80, "\n").')
+  WHERE element_id IN ('. $ids_str .')
 ;';
   pwg_query($query);
 
-  // destruction of the rates associated to this element
+  // destruction of the caddie associated to this element
   $query = '
 DELETE FROM '.CADDIE_TABLE.'
-  WHERE element_id IN (
-'.wordwrap(implode(', ', $ids), 80, "\n").')
+  WHERE element_id IN ('. $ids_str .')
 ;';
   pwg_query($query);
 
   // destruction of the image
   $query = '
 DELETE FROM '.IMAGES_TABLE.'
-  WHERE id IN (
-'.wordwrap(implode(', ', $ids), 80, "\n").')
+  WHERE id IN ('. $ids_str .')
 ;';
   pwg_query($query);
 
@@ -303,8 +317,7 @@ DELETE FROM '.IMAGES_TABLE.'
 SELECT
     id
   FROM '.CATEGORIES_TABLE.'
-  WHERE representative_picture_id IN (
-'.wordwrap(implode(', ', $ids), 80, "\n").')
+  WHERE representative_picture_id IN ('. $ids_str .')
 ;';
   $category_ids = array_from_query($query, 'id');
   if (count($category_ids) > 0)
@@ -316,13 +329,13 @@ SELECT
   return count($ids);
 }
 
-// The delete_user function delete a user identified by the $user_id
-// It also deletes :
-//     - all the access linked to this user
-//     - all the links to any group
-//     - all the favorites linked to this user
-//     - calculated permissions linked to the user
-//     - all datas about notifications for the user
+/**
+ * Deletes an user.
+ * It also deletes all related data (accesses, favorites, permissions, etc.)
+ * @todo : accept array input
+ *
+ * @param int $user_id
+ */
 function delete_user($user_id)
 {
   global $conf;
@@ -356,7 +369,7 @@ DELETE FROM '.$table.'
     pwg_query($query);
   }
 
-  // destruction of the user
+  // purge of sessions
   $query = '
 DELETE FROM '.SESSIONS_TABLE.'
   WHERE data LIKE \'pwg_uid|i:'.(int)$user_id.';%\'
@@ -415,10 +428,9 @@ SELECT
 
 /**
  * Verifies that the representative picture really exists in the db and
- * picks up a random represantive if possible and based on config.
+ * picks up a random representative if possible and based on config.
  *
- * @param mixed category id
- * @returns void
+ * @param 'all'|int|int[] $ids
  */
 function update_category($ids = 'all')
 {
@@ -485,9 +497,8 @@ SELECT DISTINCT id
 }
 
 /**
- * check and repair images integrity
- *
- * TODO see delete_elements function to check all linked tables
+ * Checks and repairs IMAGE_CATEGORY_TABLE integrity.
+ * Removes all entries from the table which correspond to a deleted image.
  */
 function images_integrity()
 {
@@ -513,18 +524,18 @@ DELETE
 }
 
 /**
- * returns an array containing sub-directories which can be a category,
- * recursive by default
- *
- * directories nammed "thumbnail", "pwg_high" or "pwg_representative" are
- * omitted
+ * Returns an array containing sub-directories which are potentially
+ * a category.
+ * Directories named ".svn", "thumbnail", "pwg_high" or "pwg_representative"
+ * are omitted.
  *
- * @param string $basedir
- * @return array
+ * @param string $basedir (eg: ./galleries)
+ * @return string[]
  */
 function get_fs_directories($path, $recursive = true)
 {
   $dirs = array();
+  $path = rtrim($path, '/');
 
   if (is_dir($path))
   {
@@ -555,9 +566,8 @@ function get_fs_directories($path, $recursive = true)
 }
 
 /**
- * order categories (update categories.rank and global_rank database fields)
- * so that rank field are consecutive integers starting at 1 for each child
- * @return void
+ * Orders categories (update categories.rank and global_rank database fields)
+ * so that rank field are consecutive integers starting at 1 for each child.
  */
 function update_global_rank()
 {
@@ -623,22 +633,21 @@ SELECT id, id_uppercat, uppercats, rank, global_rank
 }
 
 /**
- * change the visible property on a set of categories
+ * Change the **visible** property on a set of categories.
  *
- * @param array categories
- * @param string value
- * @return void
+ * @param int[] $categories
+ * @param boolean|string $value
  */
 function set_cat_visible($categories, $value)
 {
-  if (!in_array($value, array('true', 'false')))
+  if ( ($value = filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE)) === null )
   {
     trigger_error("set_cat_visible invalid param $value", E_USER_WARNING);
     return false;
   }
 
   // unlocking a category => all its parent categories become unlocked
-  if ($value == 'true')
+  if ($value)
   {
     $uppercats = get_uppercat_ids($categories);
     $query = '
@@ -648,7 +657,7 @@ UPDATE '.CATEGORIES_TABLE.'
     pwg_query($query);
   }
   // locking a category   => all its child categories become locked
-  if ($value == 'false')
+  else
   {
     $subcats = get_subcat_ids($categories);
     $query = '
@@ -660,11 +669,10 @@ UPDATE '.CATEGORIES_TABLE.'
 }
 
 /**
- * change the status property on a set of categories : private or public
+ * Change the **status** property on a set of categories : private or public.
  *
- * @param array categories
- * @param string value
- * @return void
+ * @param int[] $categories
+ * @param string $value
  */
 function set_cat_status($categories, $value)
 {
@@ -698,10 +706,10 @@ UPDATE '.CATEGORIES_TABLE.'
 }
 
 /**
- * returns all uppercats category ids of the given category ids
+ * Returns all uppercats category ids of the given category ids.
  *
- * @param array cat_ids
- * @return array
+ * @param int[] $cat_ids
+ * @return int[]
  */
 function get_uppercat_ids($cat_ids)
 {
@@ -729,9 +737,9 @@ SELECT uppercats
 }
 
 /**
- * set a new random representant to the categories
+ * Set a new random representant to the categories.
  *
- * @param array categories
+ * @param int[] $categories
  */
 function set_random_representant($categories)
 {
@@ -764,10 +772,10 @@ SELECT image_id
 }
 
 /**
- * returns the fulldir for each given category id
+ * Returns the fulldir for each given category id.
  *
- * @param array cat_ids
- * @return array
+ * @param int[] intcat_ids
+ * @return string[]
  */
 function get_fulldirs($cat_ids)
 {
@@ -816,11 +824,10 @@ SELECT id, uppercats, site_id
 }
 
 /**
- * returns an array with all file system files according to
- * $conf['file_ext']
+ * Returns an array with all file system files according to $conf['file_ext']
  *
  * @param string $path
- * @param bool recursive
+ * @param bool $recursive
  * @return array
  */
 function get_fs($path, $recursive = true)
@@ -902,14 +909,12 @@ function get_fs($path, $recursive = true)
 }
 
 /**
- * synchronize base users list and related users list
+ * Synchronize base users list and related users list.
  *
- * compares and synchronizes base users table (USERS_TABLE) with its child
+ * Compares and synchronizes base users table (USERS_TABLE) with its child
  * tables (USER_INFOS_TABLE, USER_ACCESS, USER_CACHE, USER_GROUP) : each
  * base user must be present in child tables, users in child tables not
  * present in base table must be deleted.
- *
- * @return void
  */
 function sync_users()
 {
@@ -971,10 +976,7 @@ DELETE
 }
 
 /**
- * updates categories.uppercats field based on categories.id +
- * categories.id_uppercat
- *
- * @return void
+ * Updates categories.uppercats field based on categories.id + categories.id_uppercat
  */
 function update_uppercats()
 {
@@ -1010,9 +1012,7 @@ SELECT id, id_uppercat, uppercats
 }
 
 /**
- * update images.path field
- *
- * @return void
+ * Update images.path field base on images.file and storage categories fulldirs.
  */
 function update_path()
 {
@@ -1036,12 +1036,11 @@ UPDATE '.IMAGES_TABLE.'
 }
 
 /**
- * change the parent category of the given categories. The categories are
+ * Change the parent category of the given categories. The categories are
  * supposed virtual.
  *
- * @param array category identifiers
- * @param int parent category identifier
- * @return void
+ * @param int[] $category_ids
+ * @param int $new_parent (-1 for root)
  */
 function move_categories($category_ids, $new_parent = -1)
 {
@@ -1095,11 +1094,10 @@ SELECT uppercats
     }
   }
 
-  $tables =
-    array(
-      USER_ACCESS_TABLE => 'user_id',
-      GROUP_ACCESS_TABLE => 'group_id'
-      );
+  $tables = array(
+    USER_ACCESS_TABLE => 'user_id',
+    GROUP_ACCESS_TABLE => 'group_id'
+    );
 
   $query = '
 UPDATE '.CATEGORIES_TABLE.'
@@ -1175,11 +1173,17 @@ DELETE FROM '.$table.'
 }
 
 /**
- * create a virtual category
+ * Create a virtual category.
  *
- * @param string category name
- * @param int parent category id
- * @return array with ('info' and 'id') or ('error') key
+ * @param string $category_name
+ * @param int $parent_id
+ * @param array $options
+ *    - boolean commentable
+ *    - boolean visible
+ *    - string status
+ *    - string comment
+ *    - boolean inherit
+ * @return array ('info', 'id') or ('error')
  */
 function create_virtual_category($category_name, $parent_id=null, $options=array())
 {
@@ -1322,12 +1326,11 @@ SELECT id, uppercats, global_rank, visible, status
 }
 
 /**
- * Set tags to an image. Warning: given tags are all tags associated to the
- * image, not additionnal tags.
+ * Set tags to an image.
+ * Warning: given tags are all tags associated to the image, not additionnal tags.
  *
- * @param array tag ids
- * @param int image id
- * @return void
+ * @param int[] $tags
+ * @param int $image_id
  */
 function set_tags($tags, $image_id)
 {
@@ -1337,9 +1340,8 @@ function set_tags($tags, $image_id)
 /**
  * Add new tags to a set of images.
  *
- * @param array tag ids
- * @param array image ids
- * @return void
+ * @param int[] $tags
+ * @param int[] $images
  */
 function add_tags($tags, $images)
 {
@@ -1378,7 +1380,9 @@ DELETE
 }
 
 /**
+ * Delete tags and tags associations.
  *
+ * @param int[] $tag_ids
  */
 function delete_tags($tag_ids)
 {
@@ -1409,7 +1413,13 @@ DELETE
   invalidate_user_cache_nb_tags();
 }
 
-function tag_id_from_tag_name($tag_name)
+/**
+ * Returns a tag id from its name. If nothing found, create a new tag.
+ *
+ * @param string $tag_name
+ * @return int
+ */
+function tag_id_from_tag_name($tag_name, $create=true)
 {
   global $page;
 
@@ -1454,6 +1464,9 @@ SELECT id
               )
             )
           );
+
+        invalidate_user_cache_nb_tags();
+
         $page['tag_id_from_tag_name_cache'][$tag_name] = pwg_db_insert_id(TAGS_TABLE);
         return $page['tag_id_from_tag_name_cache'][$tag_name];
       }
@@ -1464,6 +1477,11 @@ SELECT id
   return $page['tag_id_from_tag_name_cache'][$tag_name];
 }
 
+/**
+ * Set tags of images. Overwrites all existing associations.
+ *
+ * @param array $tags_of - keys are image ids, values are array of tag ids
+ */
 function set_tags_of($tags_of)
 {
   if (count($tags_of) > 0)
@@ -1503,12 +1521,10 @@ DELETE
 
 /**
  * Associate a list of images to a list of categories.
+ * The function will not duplicate links and will preserve ranks.
  *
- * The function will not duplicate links and will preserve ranks
- *
- * @param array images
- * @param array categories
- * @return void
+ * @param int[] $images
+ * @param int[] $categories
  */
 function associate_images_to_categories($images, $categories)
 {
@@ -1595,12 +1611,10 @@ SELECT
 /**
  * Dissociate images from all old categories except their storage category and
  * associate to new categories.
+ * This function will preserve ranks.
  *
- * This function will preserve ranks
- *
- * @param array images
- * @param array categories
- * @return void
+ * @param int[] $images
+ * @param int[] $categories
  */
 function move_images_to_categories($images, $categories)
 {
@@ -1639,9 +1653,8 @@ DELETE '.IMAGE_CATEGORY_TABLE.'.*
  * Associate images associated to a list of source categories to a list of
  * destination categories.
  *
- * @param array sources
- * @param array destinations
- * @return void
+ * @param int[] $sources
+ * @param int[] $destinations
  */
 function associate_categories_to_categories($sources, $destinations)
 {
@@ -1663,8 +1676,7 @@ SELECT image_id
 /**
  * Refer main Piwigo URLs (currently PHPWG_DOMAIN domain)
  *
- * @param void
- * @return array like $conf['links']
+ * @return string[]
  */
 function pwg_URL()
 {
@@ -1680,7 +1692,7 @@ function pwg_URL()
 }
 
 /**
- * Invalidates cahed data (permissions and category counts) for all users.
+ * Invalidates cached data (permissions and category counts) for all users.
  */
 function invalidate_user_cache($full = true)
 {
@@ -1703,11 +1715,14 @@ UPDATE '.USER_CACHE_TABLE.'
   trigger_action('invalidate_user_cache', $full);
 }
 
-
+/**
+ * Invalidates cached tags counter for all users.
+ */
 function invalidate_user_cache_nb_tags()
 {
   global $user;
   unset($user['nb_available_tags']);
+
   $query = '
 UPDATE '.USER_CACHE_TABLE.'
   SET nb_available_tags = NULL';
@@ -1715,9 +1730,11 @@ UPDATE '.USER_CACHE_TABLE.'
 }
 
 /**
- * adds the caracter set to a create table sql query.
- * all CREATE TABLE queries must call this function
- * @param string query - the sql query
+ * Adds the caracter set to a create table sql query.
+ * All CREATE TABLE queries must call this function
+ *
+ * @param string $query
+ * @return string
  */
 function create_table_add_character_set($query)
 {
@@ -1762,9 +1779,11 @@ function create_table_add_character_set($query)
 }
 
 /**
- * Returns array use on template with html_options method
- * @param Min and Max access to use
- * @return array of user access level
+ * Returns access levels as array used on template with html_options functions.
+ *
+ * @param int $MinLevelAccess
+ * @param int $MaxLevelAccess
+ * @return array
  */
 function get_user_access_level_html_options($MinLevelAccess = ACCESS_FREE, $MaxLevelAccess = ACCESS_CLOSED)
 {
@@ -1777,9 +1796,11 @@ function get_user_access_level_html_options($MinLevelAccess = ACCESS_FREE, $MaxL
 }
 
 /**
- * returns a list of templates currently available in template-extension
+ * returns a list of templates currently available in template-extension.
  * Each .tpl file is extracted from template-extension.
- * @return array
+ *
+ * @param string $start (internal use)
+ * @return string[]
  */
 function get_extents($start='')
 {
@@ -1804,6 +1825,12 @@ function get_extents($start='')
   return $extents;
 }
 
+/**
+ * Create a new tag.
+ *
+ * @param string $tag_name
+ * @return array ('id', info') or ('error')
+ */
 function create_tag($tag_name)
 {
   // does the tag already exists?
@@ -1841,11 +1868,10 @@ SELECT id
 
 /**
  * Is the category accessible to the (Admin) user ?
- *
  * Note : if the user is not authorized to see this category, category jump
  * will be replaced by admin cat_modify page
  *
- * @param int category id to verify
+ * @param int $category_id
  * @return bool
  */
 function cat_admin_access($category_id)
@@ -1862,10 +1888,14 @@ function cat_admin_access($category_id)
 }
 
 /**
- * Retrieve data from external URL
+ * Retrieve data from external URL.
  *
- * @param string $src: URL
- * @param global $dest: can be a file ressource or string
+ * @param string $src
+ * @param string|Ressource $dest - can be a file ressource or string
+ * @param array $get_data - data added to request url
+ * @param array $post_data - data transmitted with POST
+ * @param string $user_agent
+ * @param int $step (internal use)
  * @return bool
  */
 function fetchRemote($src, &$dest, $get_data=array(), $post_data=array(), $user_agent='Piwigo', $step=0)
@@ -2019,13 +2049,11 @@ function fetchRemote($src, &$dest, $get_data=array(), $post_data=array(), $user_
   return true;
 }
 
-
 /**
- * returns the groupname corresponding to the given group identifier if
- * exists
+ * Returns the groupname corresponding to the given group identifier if exists.
  *
- * @param int group_id
- * @return mixed
+ * @param int $group_id
+ * @return string|false
  */
 function get_groupname($group_id)
 {
@@ -2048,10 +2076,10 @@ SELECT name
 }
 
 /**
- * returns the username corresponding to the given user identifier if exists
+ * Returns the username corresponding to the given user identifier if exists.
  *
- * @param int user_id
- * @return mixed
+ * @param int $user_id
+ * @return string|false
  */
 function get_username($user_id)
 {
@@ -2075,13 +2103,22 @@ SELECT '.$conf['user_fields']['username'].'
   return stripslashes($username);
 }
 
-function get_newsletter_subscribe_base_url($language) {
+/**
+ * Get url on piwigo.org for newsletter subscription
+ *
+ * @param string $language (unused)
+ * @return string
+ */
+function get_newsletter_subscribe_base_url($language='en_UK')
+{
   return PHPWG_URL.'/announcement/subscribe/';
 }
 
 /**
- * Accordion menus need to know which section to open by default when
- * loading the page
+ * Return admin menu id for accordion.
+ *
+ * @param string $menu_page
+ * @return int
  */
 function get_active_menu($menu_page)
 {
@@ -2136,14 +2173,19 @@ function get_active_menu($menu_page)
     case 'theme':
     case 'languages':
       return 5;
+
+    default:
+      return 0;
   }
-  return 0;
 }
 
-/*
- * get tags list from SQL query (ids are surrounded by ~~, for get_tag_ids())
- * @param string: query
- * @param boolean: only_user_language, if true, only local name is returned for multilingual tags
+/**
+ * Get tags list from SQL query (ids are surrounded by ~~, for get_tag_ids()).
+ *
+ * @param string $query
+ * @param boolean $only_user_language - if true, only local name is returned for
+ *    multilingual tags (if ExtendedDescription plugin is active)
+ * @return array[] ('id', 'name')
  */
 function get_taglist($query, $only_user_language=true)
 {
@@ -2185,18 +2227,20 @@ function get_taglist($query, $only_user_language=true)
   return $taglist;
 }
 
-/*
- * get tags ids from a list of raw tags (existing tags or new tags)
- * @param mixed: raw_tags, array or comma separated string
- * @param boolean: allow_create
+/**
+ * Get tags ids from a list of raw tags (existing tags or new tags).
+ *
+ * In $raw_tags we receive something like array('~~6~~', '~~59~~', 'New
+ * tag', 'Another new tag') The ~~34~~ means that it is an existing
+ * tag. We added the surrounding ~~ to permit creation of tags like "10"
+ * or "1234" (numeric characters only)
+ *
+ * @param string|string[] $raw_tags - array or comma separated string
+ * @param boolean $allow_create
+ * @return int[]
  */
 function get_tag_ids($raw_tags, $allow_create=true)
 {
-  // In $raw_tags we receive something like array('~~6~~', '~~59~~', 'New
-  // tag', 'Another new tag') The ~~34~~ means that it is an existing
-  // tag. I've added the surrounding ~~ to permit creation of tags like "10"
-  // or "1234" (numeric characters only)
-
   $tag_ids = array();
   if (!is_array($raw_tags))
   {
@@ -2219,11 +2263,16 @@ function get_tag_ids($raw_tags, $allow_create=true)
   return $tag_ids;
 }
 
-/** returns the argument_ids array with new sequenced keys based on related
+/**
+ * Returns the argument_ids array with new sequenced keys based on related
  * names. Sequence is not case sensitive.
- * Warning: By definition, this function breaks original keys
+ * Warning: By definition, this function breaks original keys.
+ *
+ * @param int[] $elements_ids
+ * @param string[] $name - names of elements, indexed by ids
+ * @return int[]
  */
-function order_by_name($element_ids,$name)
+function order_by_name($element_ids, $name)
 {
   $ordered_element_ids = array();
   foreach ($element_ids as $k_id => $element_id)
@@ -2235,14 +2284,18 @@ function order_by_name($element_ids,$name)
   return $ordered_element_ids;
 }
 
+/**
+ * Grant access to a list of categories for a list of users.
+ *
+ * @param int[] $category_ids
+ * @param int[] $user_ids
+ */
 function add_permission_on_category($category_ids, $user_ids)
 {
-  // array-ify categories and users
   if (!is_array($category_ids))
   {
     $category_ids = array($category_ids);
   }
-
   if (!is_array($user_ids))
   {
     $user_ids = array($user_ids);
@@ -2294,7 +2347,12 @@ SELECT id
     );
 }
 
-
+/**
+ * Returns the list of admin users.
+ *
+ * @param boolean $include_webmaster
+ * @return int[]
+ */
 function get_admins($include_webmaster=true)
 {
   $status_list = array('admin');
@@ -2314,7 +2372,11 @@ SELECT
   return array_from_query($query, 'user_id');
 }
 
-/** delete all derivative files for one or several types */
+/**
+ * Delete all derivative files for one or several types
+ *
+ * @param 'all'|int[] $types
+ */
 function clear_derivative_cache($types='all')
 {
   if ($types === 'all')
@@ -2371,6 +2433,10 @@ function clear_derivative_cache($types='all')
   }
 }
 
+/**
+ * Used by clear_derivative_cache()
+ * @ignore
+ */
 function clear_derivative_cache_rec($path, $pattern)
 {
   $rmdir = true;
@@ -2417,6 +2483,12 @@ function clear_derivative_cache_rec($path, $pattern)
   }
 }
 
+/**
+ * Deletes derivatives of a particular element
+ *
+ * @param array $infos ('path'[, 'representative_ext'])
+ * @param 'all'|int $type
+ */
 function delete_element_derivatives($infos, $type='all')
 {
   $path = $infos['path'];
@@ -2448,10 +2520,10 @@ function delete_element_derivatives($infos, $type='all')
 }
 
 /**
- * returns an array contening sub-directories, excluding ".svn"
+ * Returns an array containing sub-directories, excluding ".svn"
  *
- * @param string $dir
- * @return array
+ * @param string $directory
+ * @return string[]
  */
 function get_dirs($directory)
 {
@@ -2474,7 +2546,8 @@ function get_dirs($directory)
 }
 
 /**
- * recursively delete a directory
+ * Recursively delete a directory.
+ *
  * @param string $path
  * @param string $trash_path, try to move the directory to this path if it cannot be delete
  */