Index: /trunk/include/functions.inc.php
===================================================================
--- /trunk/include/functions.inc.php	(revision 25811)
+++ /trunk/include/functions.inc.php	(revision 25812)
@@ -37,6 +37,4 @@
 include_once( PHPWG_ROOT_PATH .'include/derivative_std_params.inc.php');
 include_once( PHPWG_ROOT_PATH .'include/derivative.inc.php');
-//require_once( PHPWG_ROOT_PATH .'include/smarty/libs/Smarty.class.php');
-require_once( PHPWG_ROOT_PATH .'include/smarty/libs/SmartyBC.class.php');
 include_once( PHPWG_ROOT_PATH .'include/template.class.php');
 
Index: /trunk/include/template.class.php
===================================================================
--- /trunk/include/template.class.php	(revision 25811)
+++ /trunk/include/template.class.php	(revision 25812)
@@ -22,35 +22,59 @@
 // +-----------------------------------------------------------------------+
 
+/**
+ * @package template
+ */
+
+//require_once( PHPWG_ROOT_PATH .'include/smarty/libs/Smarty.class.php');
+require_once( PHPWG_ROOT_PATH .'include/smarty/libs/SmartyBC.class.php');
+
+
+/** default rank for buttons */
 define('BUTTONS_RANK_NEUTRAL', 50);
 
-class Template {
-
+/**
+ * This a wrapper arround Smarty classes proving various custom mechanisms for templates.
+ */
+class Template
+{
+  /** @var Smarty */
   var $smarty;
-
+  /** @var string */
   var $output = '';
 
-  // Hash of filenames for each template handle.
+  /** @var string[] - Hash of filenames for each template handle. */
   var $files = array();
-
-  // Template extents filenames for each template handle.
+  /** @var string[] - Template extents filenames for each template handle. */
   var $extents = array();
-
-  // Templates prefilter from external sources (plugins)
+  /** @var array - Templates prefilter from external sources (plugins) */
   var $external_filters = array();
 
-  // used by html_head smarty block to add content before </head>
+  /** @var string - Content to add before </head> tag */
   var $html_head_elements = array();
+  /** @var string - Runtime CSS rules */
   private $html_style = '';
 
+  /** @const string */
   const COMBINED_SCRIPTS_TAG = '<!-- COMBINED_SCRIPTS -->';
+  /** @var ScriptLoader */
   var $scriptLoader;
 
+  /** @const string */
   const COMBINED_CSS_TAG = '<!-- COMBINED_CSS -->';
+  /** @var CssLoader */
   var $cssLoader;
 
+  /** @var array - Runtime buttons on picture page */
   var $picture_buttons = array();
+  /** @var array - Runtime buttons on index page */
   var $index_buttons = array();
 
-  function Template($root = ".", $theme= "", $path = "template")
+
+  /**
+   * @var string $root
+   * @var string $theme
+   * @var string $path
+   */
+  function __construct($root = ".", $theme= "", $path = "template")
   {
     global $conf, $lang_info;
@@ -63,5 +87,7 @@
     $this->smarty->debugging = $conf['debug_template'];
     if (!$this->smarty->debugging)
+    {
       $this->smarty->error_reporting = error_reporting() & ~E_NOTICE;
+    }
     $this->smarty->compile_check = $conf['template_compile_check'];
     $this->smarty->force_compile = $conf['template_force_compile'];
@@ -134,5 +160,11 @@
 
   /**
-   * Load theme's parameters.
+   * Loads theme's parameters.
+   *
+   * @param string $root
+   * @param string $theme
+   * @param string $path
+   * @param bool $load_css
+   * @param bool $load_local_head
    */
   function set_theme($root, $theme, $path, $load_css=true, $load_local_head=true)
@@ -167,6 +199,8 @@
 
   /**
-   * Add template directory for this Template object.
-   * Set compile id if not exists.
+   * Adds template directory for this Template object.
+   * Also set compile id if not exists.
+   *
+   * @param string $dir
    */
   function set_template_dir($dir)
@@ -184,4 +218,6 @@
   /**
    * Gets the template root directory for this Template object.
+   *
+   * @return string
    */
   function get_template_dir()
@@ -202,4 +238,10 @@
   }
 
+  /**
+   * Returns theme's parameter.
+   *
+   * @param string $val
+   * @return mixed
+   */
   function get_themeconf($val)
   {
@@ -210,4 +252,8 @@
   /**
    * Sets the template filename for handle.
+   *
+   * @param string $handle
+   * @param string $filename
+   * @return bool
    */
   function set_filename($handle, $filename)
@@ -217,6 +263,8 @@
 
   /**
-   * Sets the template filenames for handles. $filename_array should be a
-   * hash of handle => filename pairs.
+   * Sets the template filenames for handles.
+   *
+   * @param string[] $filename_array hashmap of handle=>filename
+   * @return true
    */
   function set_filenames($filename_array)
@@ -243,4 +291,11 @@
   /**
    * Sets template extention filename for handles.
+   *
+   * @param string $filename
+   * @param mixed $param
+   * @param string $dir
+   * @param bool $overwrite
+   * @param string $theme
+   * @return bool
    */
   function set_extent($filename, $param, $dir='', $overwrite=true, $theme='N/A')
@@ -251,5 +306,10 @@
   /**
    * Sets template extentions filenames for handles.
-   * $filename_array should be an hash of filename => array( handle, param) or filename => handle
+   *
+   * @param string[] $filename_array hashmap of handle=>filename
+   * @param string $dir
+   * @param bool $overwrite
+   * @param string $theme
+   * @return bool
    */
   function set_extents($filename_array, $dir='', $overwrite=true, $theme='N/A')
@@ -289,5 +349,11 @@
   }
 
-  /** return template extension if exists  */
+  /**
+   * Returns template extension if exists.
+   *
+   * @param string $filename should be empty!
+   * @param string $handle
+   * @return string
+   */
   function get_extent($filename='', $handle='')
   {
@@ -299,6 +365,13 @@
   }
 
-  /** see smarty assign http://www.smarty.net/manual/en/api.assign.php */
-  function assign($tpl_var, $value = null)
+  /**
+   * Assigns a template variable.
+   * @see http://www.smarty.net/manual/en/api.assign.php
+   *
+   * @param string|array $tpl_var can be a var name or a hashmap of variables
+   *    (in this case, do not use the _$value_ parameter)
+   * @param mixed $value
+   */
+  function assign($tpl_var, $value=null)
   {
     $this->smarty->assign( $tpl_var, $value );
@@ -306,8 +379,11 @@
 
   /**
-   * Inserts the uncompiled code for $handle as the value of $varname in the
-   * root-level. This can be used to effectively include a template in the
-   * middle of another template.
-   * This is equivalent to assign($varname, $this->parse($handle, true))
+   * Defines _$varname_ as the compiled result of _$handle_.
+   * This can be used to effectively include a template in another template.
+   * This is equivalent to assign($varname, $this->parse($handle, true)).
+   *
+   * @param string $varname
+   * @param string $handle
+   * @return true
    */
   function assign_var_from_handle($varname, $handle)
@@ -317,5 +393,12 @@
   }
 
-  /** see smarty append http://www.smarty.net/manual/en/api.append.php */
+  /**
+   * Appends a new value in a template array variable, the variable is created if needed.
+   * @see http://www.smarty.net/manual/en/api.append.php
+   *
+   * @param string $tpl_var
+   * @param mixed $value
+   * @param bool $merge
+   */
   function append($tpl_var, $value=null, $merge=false)
   {
@@ -324,6 +407,8 @@
 
   /**
-   * Root-level variable concatenation. Appends a  string to an existing
-   * variable assignment with the same name.
+   * Performs a string concatenation.
+   *
+   * @param string $tpl_var
+   * @param string $value
    */
   function concat($tpl_var, $value)
@@ -333,5 +418,10 @@
   }
 
-  /** see smarty append http://www.smarty.net/manual/en/api.clear_assign.php */
+  /**
+   * Removes an assigned template variable.
+   * @see http://www.smarty.net/manual/en/api.clear_assign.php
+   *
+   * @param string $tpl_var
+   */
   function clear_assign($tpl_var)
   {
@@ -339,15 +429,22 @@
   }
 
-  /** see smarty get_template_vars http://www.smarty.net/manual/en/api.get_template_vars.php */
-  function get_template_vars($name=null)
-  {
-    return $this->smarty->getTemplateVars( $name );
-  }
-
-
-  /**
-   * Load the file for the handle, eventually compile the file and run the compiled
-   * code. This will add the output to the results or return the result if $return
-   * is true.
+  /**
+   * Returns an assigned template variable.
+   * @see http://www.smarty.net/manual/en/api.get_template_vars.php
+   *
+   * @param string $tpl_var
+   */
+  function get_template_vars($tpl_var=null)
+  {
+    return $this->smarty->getTemplateVars( $tpl_var );
+  }
+
+  /**
+   * Loads the template file of the handle, compiles it and appends the result to the output
+   * (or returns it if _$return_ is true).
+   *
+   * @param string $handle
+   * @param bool $return
+   * @return null|string
    */
   function parse($handle, $return=false)
@@ -382,6 +479,8 @@
 
   /**
-   * Load the file for the handle, eventually compile the file and run the compiled
-   * code. This will print out the results of executing the template.
+   * Loads the template file of the handle, compiles it and appends the result to the output,
+   * then sends the output to the browser.
+   *
+   * @param string $handle
    */
   function pparse($handle)
@@ -391,4 +490,7 @@
   }
 
+  /**
+   * Load and compile JS & CSS into the template and sends the output to the browser.
+   */
   function flush()
   {
@@ -450,5 +552,8 @@
   }
 
-  /** flushes the output */
+  /**
+   * Same as flush() but with optional debugging.
+   * @see Template::flush()
+   */
   function p()
   {
@@ -467,4 +572,10 @@
   }
 
+  /**
+   * Eval a temp string to retrieve the original PHP value.
+   *
+   * @param string $str
+   * @return mixed
+   */
   static function get_php_str_val($str)
   {
@@ -482,5 +593,12 @@
 
   /**
-   * translate variable modifier - translates a text to the currently loaded language
+   * "translate" variable modifier.
+   * Usage : 
+   *    - {'Comment'|translate}
+   *    - {'%d comments'|translate:$count}
+   * @see l10n()
+   *
+   * @param array $params
+   * @return string
    */
   static function modcompiler_translate($params)
@@ -512,4 +630,13 @@
   }
 
+  /**
+   * "translate_dec" variable modifier.
+   * Usage :
+   *    - {$count|translate_dec:'%d comment':'%d comments'}
+   * @see l10n_dec()
+   *
+   * @param array $params
+   * @return string
+   */
   static function modcompiler_translate_dec($params)
   {
@@ -538,6 +665,11 @@
 
   /**
-   * explode variable modifier - similar to php explode
-   * 'Yes;No'|@explode:';' -> array('Yes', 'No')
+   * "explode" variable modifier.
+   * Usage :
+   *    - {assign var=valueExploded value=$value|@explode:','}
+   *
+   * @param string $text
+   * @param string $delimiter
+   * @return array
    */
   static function mod_explode($text, $delimiter=',')
@@ -547,8 +679,9 @@
 
   /**
-   * This smarty "html_head" block allows to add content just before
-   * </head> element in the output after the head has been parsed. This is
-   * handy in order to respect strict standards when <style> and <link>
-   * html elements must appear in the <head> element
+   * The "html_head" block allows to add content just before
+   * </head> element in the output after the head has been parsed.
+   *
+   * @param array $params (unused)
+   * @param string $content
    */
   function block_html_head($params, $content)
@@ -561,4 +694,11 @@
   }
 
+  /**
+   * The "html_style" block allows to add CSS juste before
+   * </head> element in the output after the head has been parsed.
+   *
+   * @param array $params (unused)
+   * @param string $content
+   */
   function block_html_style($params, $content)
   {
@@ -570,4 +710,18 @@
   }
 
+  /**
+   * The "define_derivative" function allows to define derivative from tpl file.
+   * It assigns a DerivativeParams object to _name_ template variable.
+   *
+   * @param array $params
+   *    - name (required)
+   *    - type (optional)
+   *    - width (required if type is empty)
+   *    - height (required if type is empty)
+   *    - crop (optional, used if type is empty)
+   *    - min_height (optional, used with crop)
+   *    - min_height (optional, used with crop)
+   * @param Smarty $smarty
+   */
   function func_define_derivative($params, $smarty)
   {
@@ -611,16 +765,16 @@
   }
 
-   /**
-    * combine_script smarty function allows inclusion of a javascript file in the current page.
-    * The engine will combine several js files into a single one in order to reduce the number of
-    * required http requests.
-    * param id - required
-    * param path - required - the path to js file RELATIVE to piwigo root dir
-    * param load - optional - header|footer|async, default header
-    * param require - optional - comma separated list of script ids required to be loaded and executed
-        before this one
-    * param version - optional - plugins could use this and change it in order to force a
-        browser refresh
-    */
+  /**
+   * The "combine_script" functions allows inclusion of a javascript file in the current page.
+   * The engine will combine several js files into a single one.
+   *
+   * @param array $params
+   *   - id (required)
+   *   - path (required)
+   *   - load (optional) 'header', 'footer' or 'async'
+   *   - require (optional) comma separated list of script ids required to be loaded
+   *     and executed before this one
+   *   - version (optional) used to force a browser refresh
+   */
   function func_combine_script($params)
   {
@@ -647,5 +801,11 @@
   }
 
-
+  /**
+   * The "get_combined_scripts" function returns HTML tag of combined scripts.
+   * It can returns a placeholder for delayed JS files combination and minification.
+   *
+   * @param array $params
+   *    - load (required)
+   */
   function func_get_combined_scripts($params)
   {
@@ -699,6 +859,11 @@
   }
 
-
-  private static function make_script_src( $script )
+  /**
+   * Returns clean relative URL to script file.
+   *
+   * @param Combinable $script
+   * @return string
+   */
+  private static function make_script_src($script)
   {
     $ret = '';
@@ -718,4 +883,11 @@
   }
 
+  /**
+   * The "footer_script" block allows to add runtime script in the HTML page.
+   *
+   * @param array $params
+   *    - require (optional) comma separated list of script ids
+   * @param string $content
+   */
   function block_footer_script($params, $content)
   {
@@ -732,11 +904,14 @@
 
   /**
-    * combine_css smarty function allows inclusion of a css stylesheet file in the current page.
-    * The engine will combine several css files into a single one in order to reduce the number of
-    * required http requests.
-    * param path - required - the path to css file RELATIVE to piwigo root dir
-    * param version - optional - plugins could use this and change it in order to force a
-        browser refresh
-    */
+   * The "combine_css" function allows inclusion of a css file in the current page.
+   * The engine will combine several css files into a single one.
+   *
+   * @param array $params
+   *    - id (optional) used to deal with multiple inclusions from plugins
+   *    - path (required)
+   *    - version (optional) used to force a browser refresh
+   *    - order (optional)
+   *    - template (optional) set to true to allow smarty syntax in the css file
+   */
   function func_combine_css($params)
   {
@@ -754,4 +929,10 @@
   }
 
+  /**
+   * The "get_combined_scripts" function returns a placeholder for delayed
+   * CSS files combination and minification.
+   *
+   * @param array $params (unused)
+   */
   function func_get_combined_css($params)
   {
@@ -759,10 +940,13 @@
   }
 
-
- /**
-   * This function allows to declare a Smarty prefilter from a plugin, thus allowing
-   * it to modify template source before compilation and without changing core files
+  /**
+   * Declares a Smarty prefilter from a plugin, allowing it to modify template
+   * source before compilation and without changing core files.
    * They will be processed by weight ascending.
-   * http://www.smarty.net/manual/en/advanced.features.prefilters.php
+   * @see http://www.smarty.net/manual/en/advanced.features.prefilters.php
+   *
+   * @param string $handle
+   * @param Callable $callback
+   * @param int $weight
    */
   function set_prefilter($handle, $callback, $weight=50)
@@ -772,4 +956,13 @@
   }
 
+  /**
+   * Declares a Smarty postfilter.
+   * They will be processed by weight ascending.
+   * @see http://www.smarty.net/manual/en/advanced.features.postfilters.php
+   *
+   * @param string $handle
+   * @param Callable $callback
+   * @param int $weight
+   */
   function set_postfilter($handle, $callback, $weight=50)
   {
@@ -778,4 +971,13 @@
   }
 
+  /**
+   * Declares a Smarty outputfilter.
+   * They will be processed by weight ascending.
+   * @see http://www.smarty.net/manual/en/advanced.features.outputfilters.php
+   *
+   * @param string $handle
+   * @param Callable $callback
+   * @param int $weight
+   */
   function set_outputfilter($handle, $callback, $weight=50)
   {
@@ -784,8 +986,8 @@
   }
 
- /**
-   * This function actually triggers the filters on the tpl files.
-   * Called in the parse method.
-   * http://www.smarty.net/manual/en/advanced.features.prefilters.php
+  /**
+   * Register the filters for the tpl file.
+   *
+   * @param string $handle
    */
   function load_external_filters($handle)
@@ -807,4 +1009,9 @@
   }
 
+  /**
+   * Unregister the filters for the tpl file.
+   *
+   * @param string $handle
+   */
   function unload_external_filters($handle)
   {
@@ -822,4 +1029,11 @@
   }
 
+  /**
+   * @toto : description of Template::prefilter_white_space
+   *
+   * @param string $source
+   * @param Smarty $smarty
+   * @param return string
+   */
   static function prefilter_white_space($source, $smarty)
   {
@@ -846,5 +1060,9 @@
 
   /**
-   * Smarty postfilter
+   * Postfilter used when $conf['compiled_template_cache_language'] is true.
+   *
+   * @param string $source
+   * @param Smarty $smarty
+   * @param return string
    */
   static function postfilter_language($source, $smarty)
@@ -858,4 +1076,11 @@
   }
 
+  /**
+   * Prefilter used to add theme local CSS files.
+   *
+   * @param string $source
+   * @param Smarty $smarty
+   * @param return string
+   */
   static function prefilter_local_css($source, $smarty)
   {
@@ -883,4 +1108,10 @@
   }
 
+  /**
+   * Loads the configuration file from a theme directory and returns it.
+   *
+   * @param string $dir
+   * @return array
+   */
   function load_themeconf($dir)
   {
@@ -898,4 +1129,10 @@
   }
 
+  /**
+   * Registers a button to be displayed on picture page.
+   *
+   * @param string $content
+   * @param int $rank
+   */
   function add_picture_button($content, $rank=BUTTONS_RANK_NEUTRAL)
   {
@@ -903,4 +1140,10 @@
   }
 
+  /**
+   * Registers a button to be displayed on index pages.
+   *
+   * @param string $content
+   * @param int $rank
+   */
   function add_index_button($content, $rank=BUTTONS_RANK_NEUTRAL)
   {
@@ -908,4 +1151,7 @@
   }
 
+  /**
+   * Assigns PLUGIN_PICTURE_BUTTONS template variable with registered picture buttons.
+   */
   function parse_picture_buttons()
   {
@@ -922,4 +1168,7 @@
   }
 
+  /**
+   * Assigns PLUGIN_INDEX_BUTTONS template variable with registered index buttons.
+   */
   function parse_index_buttons()
   {
@@ -935,5 +1184,4 @@
     }
   }
-
 }
 
