Index: /trunk/include/functions_comment.inc.php
===================================================================
--- /trunk/include/functions_comment.inc.php	(revision 25547)
+++ /trunk/include/functions_comment.inc.php	(revision 25548)
@@ -22,5 +22,20 @@
 // +-----------------------------------------------------------------------+
 
-//returns string action to perform on a new comment: validate, moderate, reject
+/**
+ * @package functions\comment
+ */
+ 
+
+add_event_handler('user_comment_check', 'user_comment_check',
+  EVENT_HANDLER_PRIORITY_NEUTRAL, 2);
+
+/**
+ * Does basic check on comment and returns action to perform.
+ * This method is called by a trigger_event()
+ *
+ * @param string $action before check
+ * @param array $comment
+ * @return string validate, moderate, reject
+ */
 function user_comment_check($action, $comment)
 {
@@ -55,16 +70,13 @@
 }
 
-
-add_event_handler('user_comment_check', 'user_comment_check',
-  EVENT_HANDLER_PRIORITY_NEUTRAL, 2);
-
-/**
- * Tries to insert a user comment in the database and returns one of :
- * validate, moderate, reject
- * @param array comm contains author, content, image_id
- * @param string key secret key sent back to the browser
- * @param array infos out array of messages
- */
-function insert_user_comment( &$comm, $key, &$infos )
+/**
+ * Tries to insert a user comment and returns action to perform.
+ *
+ * @param array $comm
+ * @param string $key secret key sent back to the browser
+ * @param array $infos output array of error messages
+ * @return string validate, moderate, reject
+ */
+function insert_user_comment(&$comm, $key, &$infos)
 {
   global $conf, $user;
@@ -252,14 +264,15 @@
     }
   }
+
   return $comment_action;
 }
 
 /**
- * Tries to delete a user comment in the database
- * only admin can delete all comments
- * other users can delete their own comments
- * so to avoid a new sql request we add author in where clause
- *
- * @param int or array of int comment_id
+ * Tries to delete a (or more) user comment.
+ *    only admin can delete all comments
+ *    other users can delete their own comments
+ *
+ * @param int|int[] $comment_id
+ * @return bool false if nothing deleted
  */
 function delete_user_comment($comment_id)
@@ -291,16 +304,19 @@
                   ));
     trigger_action('user_comment_deletion', $comment_id);
-  }
-}
-
-/**
- * Tries to update a user comment in the database
- * only admin can update all comments
- * users can edit their own comments if admin allow them
- * so to avoid a new sql request we add author in where clause
- *
- * @param comment_id
- * @param post_key
- * @param content
+
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Tries to update a user comment
+ *    only admin can update all comments
+ *    users can edit their own comments if admin allow them
+ *
+ * @param array $comment
+ * @param string $post_key secret key sent back to the browser
+ * @return string validate, moderate, reject
  */
 
@@ -398,4 +414,11 @@
 }
 
+/**
+ * Notifies admins about updated or deleted comment.
+ * Only used when no validation is needed, otherwise pwg_mail_notification_admins() is used.
+ *
+ * @param string $action edit, delete
+ * @param array $comment
+ */
 function email_admin($action, $comment)
 {
@@ -431,4 +454,11 @@
 }
 
+/**
+ * Returns the author id of a comment
+ *
+ * @param int $comment_id
+ * @param bool $die_on_error
+ * @return int
+ */
 function get_comment_author_id($comment_id, $die_on_error=true)
 {
@@ -458,6 +488,7 @@
 
 /**
- * Tries to validate a user comment in the database
- * @param int or array of int comment_id
+ * Tries to validate a user comment.
+ *
+ * @param int|int[] $comment_id
  */
 function validate_user_comment($comment_id)
@@ -480,12 +511,17 @@
 }
 
-
+/**
+ * Clears cache of nb comments for all users
+ */
 function invalidate_user_cache_nb_comments()
 {
   global $user;
+
   unset($user['nb_available_comments']);
+
   $query = '
 UPDATE '.USER_CACHE_TABLE.'
-  SET nb_available_comments = NULL';
+  SET nb_available_comments = NULL
+;';
   pwg_query($query);
 }
Index: /trunk/include/functions_cookie.inc.php
===================================================================
--- /trunk/include/functions_cookie.inc.php	(revision 25547)
+++ /trunk/include/functions_cookie.inc.php	(revision 25548)
@@ -22,8 +22,17 @@
 // +-----------------------------------------------------------------------+
 
-// cookie_path returns the path to use for the Piwigo cookie.
-// If Piwigo is installed on :
-// http://domain.org/meeting/gallery/category.php
-// cookie_path will return : "/meeting/gallery"
+/**
+ * @package functions\cookie
+ */
+
+
+/**
+ * Returns the path to use for the Piwigo cookie.
+ * If Piwigo is installed on :
+ * http://domain.org/meeting/gallery/
+ * it will return : "/meeting/gallery"
+ *
+ * @return string
+ */
 function cookie_path()
 {
@@ -84,7 +93,11 @@
 
 /**
- * persistently stores a variable in pwg cookie
- * @return boolean true on success
- * @see pwg_get_cookie_var
+ * Persistently stores a variable in pwg cookie.
+ * Set $value to null to delete the cookie.
+ *
+ * @param string $car
+ * @param mixed $value
+ * @param int|null $expire
+ * @return bool
  */
 function pwg_set_cookie_var($var, $value, $expire=null)
@@ -105,7 +118,10 @@
 
 /**
- * retrieves the value of a persistent variable in pwg cookie
+ * Retrieves the value of a persistent variable in pwg cookie
+ * @see pwg_set_cookie_var
+ *
+ * @param string $var
+ * @param mixed $default
  * @return mixed
- * @see pwg_set_cookie_var
  */
 function pwg_get_cookie_var($var, $default = null)
Index: /trunk/include/functions_filter.inc.php
===================================================================
--- /trunk/include/functions_filter.inc.php	(revision 25547)
+++ /trunk/include/functions_filter.inc.php	(revision 25548)
@@ -22,11 +22,13 @@
 // +-----------------------------------------------------------------------+
 
+/**
+ * @package functions\filter
+ */
 
 
 /**
- * update data of categories with filtered values
+ * Updates data of categories with filtered values
  *
- * @param array list of categories
- * @return null
+ * @param array $cats
  */
 function update_cats_with_filtered_data(&$cats)
Index: /trunk/include/functions_html.inc.php
===================================================================
--- /trunk/include/functions_html.inc.php	(revision 25547)
+++ /trunk/include/functions_html.inc.php	(revision 25548)
@@ -23,16 +23,20 @@
 
 /**
- * returns the list of categories as a HTML string
- *
- * categories string returned contains categories as given in the input
+ * @package functions\html
+ */
+
+
+/**
+ * Generates breadcrumb from categories list.
+ * Categories string returned contains categories as given in the input
  * array $cat_informations. $cat_informations array must be an array
  * of array( id=>?, name=>?, permalink=>?). If url input parameter is null,
  * returns only the categories name without links.
  *
- * @param array cat_informations
- * @param string url
- * @return string
- */
-function get_cat_display_name($cat_informations, $url = '')
+ * @param array $cat_informations
+ * @param string|null $url
+ * @return string
+ */
+function get_cat_display_name($cat_informations, $url='')
 {
   global $conf;
@@ -88,13 +92,11 @@
 
 /**
- * returns the list of categories as a HTML string, with cache of names
- *
- * categories string returned contains categories as given in the input
- * array $cat_informations. $uppercats is the list of category ids to
- * display in the right order. If url input parameter is empty, returns only
- * the categories name without links.
- *
- * @param string uppercats
- * @param string url
+ * Generates breadcrumb from categories list using a cache.
+ * @see get_cat_display_name()
+ *
+ * @param string $uppercats
+ * @param string|null $url
+ * @param bool $single_link
+ * @param string|null $link_class
  * @return string
  */
@@ -177,10 +179,26 @@
 
 /**
- * returns HTMLized comment contents retrieved from database
- *
- * newlines becomes br tags, _word_ becomes underline, /word/ becomes
- * italic, *word* becomes bolded
- *
- * @param string content
+ * Generates breadcrumb for a category.
+ * @see get_cat_display_name()
+ *
+ * @param int $cat_id
+ * @param string|null $url
+ * @return string
+ */
+function get_cat_display_name_from_id($cat_id, $url = '')
+{
+  $cat_info = get_cat_info($cat_id);
+  return get_cat_display_name($cat_info['upper_names'], $url);
+}
+
+/**
+ * Apply basic markdown transformations to a text.
+ * newlines becomes br tags
+ * _word_ becomes underline
+ * /word/ becomes italic
+ * *word* becomes bolded
+ * urls becomes a tags
+ *
+ * @param string $content
  * @return string
  */
@@ -209,11 +227,7 @@
   $content = preg_replace($pattern, $replacement, $content);
 
+  // TODO : add a trigger
+
   return $content;
-}
-
-function get_cat_display_name_from_id($cat_id, $url = '')
-{
-  $cat_info = get_cat_info($cat_id);
-  return get_cat_display_name($cat_info['upper_names'], $url);
 }
 
@@ -267,4 +281,7 @@
 }
 
+/**
+ * Callback used for sorting by name.
+ */
 function name_compare($a, $b)
 {
@@ -272,4 +289,7 @@
 }
 
+/**
+ * Callback used for sorting by name (slug) with cache.
+ */
 function tag_alpha_compare($a, $b)
 {
@@ -288,5 +308,5 @@
 
 /**
- * exits the current script (either exit or redirect)
+ * Exits the current script (or redirect to login page if not logged).
  */
 function access_denied()
@@ -315,7 +335,9 @@
 
 /**
- * exits the current script with 403 code
- * @param string msg a message to display
- * @param string alternate_url redirect to this url
+ * Exits the current script with 403 code.
+ * TODO : nice display if $template loaded
+ *
+ * @param string $msg
+ * @param string|null $alternate_url redirect to this url
  */
 function page_forbidden($msg, $alternate_url=null)
@@ -332,7 +354,9 @@
 
 /**
- * exits the current script with 400 code
- * @param string msg a message to display
- * @param string alternate_url redirect to this url
+ * Exits the current script with 400 code.
+ * TODO : nice display if $template loaded
+ *
+ * @param string $msg
+ * @param string|null $alternate_url redirect to this url
  */
 function bad_request($msg, $alternate_url=null)
@@ -349,7 +373,9 @@
 
 /**
- * exits the current script with 404 code when a page cannot be found
- * @param string msg a message to display
- * @param string alternate_url redirect to this url
+ * Exits the current script with 404 code.
+ * TODO : nice display if $template loaded
+ *
+ * @param string $msg
+ * @param string|null $alternate_url redirect to this url
  */
 function page_not_found($msg, $alternate_url=null)
@@ -366,7 +392,10 @@
 
 /**
- * exits the current script with 500 http code
- * this method can be called at any time (does not use template/language/user etc...)
- * @param string msg a message to display
+ * Exits the current script with 500 code.
+ * TODO : nice display if $template loaded
+ *
+ * @param string $msg
+ * @param string|null $title
+ * @param bool $show_trace
  */
 function fatal_error($msg, $title=null, $show_trace=true)
@@ -409,5 +438,8 @@
 }
 
-/* returns the title to be displayed above thumbnails on tag page
+/**
+ * Returns the breadcrumb to be displayed above thumbnails on tag page.
+ *
+ * @return string
  */
 function get_tags_content_title()
@@ -458,5 +490,7 @@
 
 /**
-  Sets the http status header (200,401,...)
+ * Sets the http status header (200,401,...)
+ * @param int $code
+ * @param string $text for exotic http codes
  */
 function set_status_header($code, $text='')
@@ -487,6 +521,10 @@
 }
 
-/** returns the category comment for rendering in html textual mode (subcatify)
- * this is an event handler. don't call directly
+/**
+ * Returns the category comment for rendering in html textual mode (subcatify)
+ * This method is called by a trigger_action()
+ *
+ * @param string $desc
+ * @return string
  */
 function render_category_literal_description($desc)
@@ -495,6 +533,11 @@
 }
 
-/*event handler for menu*/
-function register_default_menubar_blocks( $menu_ref_arr )
+/**
+ * Add known menubar blocks.
+ * This method is called by a trigger_event()
+ *
+ * @param BlockManager[] $menu_ref_arr
+ */
+function register_default_menubar_blocks($menu_ref_arr)
 {
   $menu = & $menu_ref_arr[0];
@@ -510,24 +553,31 @@
 
 /**
+ * Returns display name for an element.
+ * Returns 'name' if exists of name from 'file'.
+ *
+ * @param array $info at least file or name
+ * @return string
  */
 function render_element_name($info)
 {
-  $name = $info['name'];
-  if (!empty($name))
-  {
-    $name = trigger_event('render_element_name', $name);
-    return $name;
-  }
-
+  if (!empty($info['name']))
+  {
+    return trigger_event('render_element_name', $info['name']);
+  }
   return get_name_from_file($info['file']);
 }
 
+/**
+ * Returns display description for an element.
+ *
+ * @param array $info at least comment
+ * @param string $param used to identify the trigger
+ * @return string
+ */
 function render_element_description($info, $param='')
 {
-  $comment = $info['comment'];
-  if (!empty($comment))
-  {
-    $comment = trigger_event('render_element_description', $comment, $param);
-    return $comment;
+  if (!empty($info['comment']))
+  {
+    return trigger_event('render_element_description', $info['comment'], $param);
   }
   return '';
@@ -535,7 +585,12 @@
 
 /**
- * returns the title of the thumbnail based on photo properties
- */
-function get_thumbnail_title($info, $title, $comment)
+ * Add info to the title of the thumbnail based on photo properties.
+ *
+ * @param array $info hit, rating_score, nb_comments
+ * @param string $title
+ * @param string $comment
+ * @return string
+ */
+function get_thumbnail_title($info, $title, $comment='')
 {
   global $conf, $user;
@@ -571,8 +626,15 @@
   $title = htmlspecialchars(strip_tags($title));
   $title = trigger_event('get_thumbnail_title', $title, $info);
+
   return $title;
 }
 
-/** optional event handler to protect src image urls */
+/**
+ * Event handler to protect src image urls.
+ *
+ * @param string $url
+ * @param SrcImage $src_image
+ * @return string
+ */
 function get_src_image_url_protection_handler($url, $src_image)
 {
@@ -580,5 +642,11 @@
 }
 
-/** optional event handler to protect element urls */
+/**
+ * Event handler to protect element urls.
+ *
+ * @param string $url
+ * @param array $infos id, path
+ * @return string
+ */
 function get_element_url_protection_handler($url, $infos)
 {
@@ -595,5 +663,7 @@
 }
 
-
+/**
+ * Sends to the template all messages stored in $page and in the session.
+ */
 function flush_page_messages()
 {
