Index: /trunk/include/template.class.php
===================================================================
--- /trunk/include/template.class.php	(revision 25814)
+++ /trunk/include/template.class.php	(revision 25815)
@@ -76,5 +76,5 @@
    * @var string $path
    */
-  function __construct($root = ".", $theme= "", $path = "template")
+  function __construct($root=".", $theme="", $path="template")
   {
     global $conf, $lang_info;
@@ -1193,4 +1193,7 @@
 class PwgTemplateAdapter
 {
+  /**
+   * @deprecated use "translate" modifier
+   */
   function l10n($text)
   {
@@ -1198,4 +1201,7 @@
   }
 
+  /**
+   * @deprecated use "translate_dec" modifier
+   */
   function l10n_dec($s, $p, $v)
   {
@@ -1203,4 +1209,7 @@
   }
 
+  /**
+   * @deprecated use "translate" or "sprintf" modifier
+   */
   function sprintf()
   {
@@ -1209,4 +1218,9 @@
   }
 
+  /**
+   * @param string $type
+   * @param array $img
+   * @return DerivativeImage
+   */
   function derivative($type, $img)
   {
@@ -1214,4 +1228,9 @@
   }
 
+  /**
+   * @param string $type
+   * @param array $img
+   * @return string
+   */
   function derivative_url($type, $img)
   {
@@ -1221,18 +1240,34 @@
 
 
+/**
+ * A Combinable represents a JS or CSS file ready for cobination and minification.
+ */
 class Combinable
 {
+  /** @var string */
   public $id;
+  /** @var string */
   public $path;
+  /** @var string */
   public $version;
+  /** @var bool */
   public $is_template;
 
-  function __construct($id, $path, $version)
+  /**
+   * @param string $id
+   * @param string $path
+   * @param string $version
+   */
+  function __construct($id, $path, $version=0)
   {
     $this->id = $id;
     $this->set_path($path);
     $this->version = $version;
-  }
-
+    $this->is_template = false;
+  }
+
+  /**
+   * @param string $path
+   */
   function set_path($path)
   {
@@ -1241,29 +1276,56 @@
   }
 
+  /**
+   * @return bool
+   */
   function is_remote()
   {
-    return url_is_remote( $this->path ) || strncmp($this->path, '//', 2)==0;
+    return url_is_remote($this->path) || strncmp($this->path, '//', 2)==0;
   }
 }
 
+/**
+ * Implementation of Combinable for JS files.
+ */
 final class Script extends Combinable
 {
+  /** @var int 0,1,2 */
   public $load_mode;
-  public $precedents = array();
-  public $extra = array();
-
-  function __construct($load_mode, $id, $path, $version, $precedents)
+  /** @var array */
+  public $precedents;
+  /** @var array */
+  public $extra;
+
+  /**
+   * @param int 0,1,2
+   * @param string $id
+   * @param string $path
+   * @param string $version
+   * @param array $precedents
+   */
+  function __construct($load_mode, $id, $path, $version=0, $precedents=array())
   {
     parent::__construct($id, $path, $version);
     $this->load_mode = $load_mode;
     $this->precedents = $precedents;
+    $this->extra = array();
   }
 }
 
+/**
+ * Implementation of Combinable for CSS files.
+ */
 final class Css extends Combinable
 {
+  /** @var int */
   public $order;
 
-  function __construct($id, $path, $version, $order)
+  /**
+   * @param string $id
+   * @param string $path
+   * @param string $version
+   * @param int $order
+   */
+  function __construct($id, $path, $version=0, $order=0)
   {
     parent::__construct($id, $path, $version);
@@ -1273,10 +1335,12 @@
 
 
-/** Manage a list of css files */
+/**
+ * Manages a list of CSS files and combining them in a unique file.
+ */
 class CssLoader
 {
+  /** @param Css[] */
   private $registered_css;
-  
-  /** used to keep declaration order */
+  /** @param int used to keep declaration order */
   private $counter;
   
@@ -1292,4 +1356,7 @@
   }
   
+  /**
+   * @return Combinable[] array of combined CSS.
+   */
   function get_css()
   {
@@ -1299,4 +1366,7 @@
   }
   
+  /**
+   * Callback for CSS files sorting.
+   */
   private static function cmp_by_order($a, $b)
   {
@@ -1304,4 +1374,14 @@
   }
   
+  /**
+   * Adds a new file, if a file with the same $id already exsists, the one with
+   * the higher $order or higher $version is kept.
+   *
+   * @param string $id
+   * @param string $path
+   * @param string $version
+   * @param int $order
+   * @param bool $is_template
+   */
   function add($id, $path, $version=0, $order=0, $is_template=false)
   {
@@ -1327,13 +1407,20 @@
 
 
-/** Manage a list of required scripts for a page, by optimizing their loading location (head, bottom, async)
-and later on by combining them in a unique file respecting at the same time dependencies.*/
+/**
+ * Manage a list of required scripts for a page, by optimizing their loading location (head, footer, async)
+ * and later on by combining them in a unique file respecting at the same time dependencies.
+ */
 class ScriptLoader
 {
+  /** @var Script[] */
   private $registered_scripts;
+  /** @var string[] */
   public $inline_scripts;
 
+  /** @var bool */
   private $did_head;
+  /** @var bool */
   private $head_done_scripts;
+  /** @var bool */
   private $did_footer;
 
@@ -1364,4 +1451,15 @@
   }
 
+  /**
+   * @return bool
+   */
+  function did_head()
+  {
+    return $this->did_head;
+  }
+
+  /**
+   * @return Script[]
+   */
   function get_all()
   {
@@ -1369,4 +1467,8 @@
   }
 
+  /**
+   * @param string $code
+   * @param string[] $require
+   */
   function add_inline($code, $require)
   {
@@ -1386,4 +1488,11 @@
   }
 
+  /**
+   * @param string $id
+   * @param int $load_mode
+   * @param string[] $require
+   * @param string $path
+   * @param string $version
+   */
   function add($id, $load_mode, $require, $path, $version=0)
   {
@@ -1431,9 +1540,9 @@
   }
 
-  function did_head()
-  {
-    return $this->did_head;
-  }
-
+  /**
+   * Returns combined scripts loaded in header.
+   *
+   * @return Combinable[]
+   */
   function get_head_scripts()
   {
@@ -1459,4 +1568,9 @@
   }
 
+  /**
+   * Returns combined scripts loaded in footer.
+   *
+   * @return Combinable[]
+   */
   function get_footer_scripts()
   {
@@ -1490,4 +1604,9 @@
   }
 
+  /**
+   * @param Script[] $scripts
+   * @param int $load_mode
+   * @return Combinable[]
+   */
   private static function do_combine($scripts, $load_mode)
   {
@@ -1496,5 +1615,10 @@
   }
 
-  // checks that if B depends on A, then B->load_mode >= A->load_mode in order to respect execution order
+  /**
+   * Checks dependencies among Scripts.
+   * Checks that if B depends on A, then B->load_mode >= A->load_mode in order to respect execution order.
+   *
+   * @param Script[] $scripts
+   */
   private static function check_load_dep($scripts)
   {
@@ -1526,5 +1650,10 @@
   }
 
-
+  /**
+   * Fill a script dependancies with the known jQuery UI scripts.
+   *
+   * @param string $id in FileCombiner::$known_paths
+   * @param Script $script
+   */
   private static function fill_well_known($id, $script)
   {
@@ -1561,4 +1690,11 @@
   }
 
+  /**
+   * Add a known jQuery UI script to loaded scripts.
+   *
+   * @param string $id in FileCombiner::$known_paths
+   * @param int $load_mode
+   * @return bool
+   */
   private function load_known_required_script($id, $load_mode)
   {
@@ -1571,4 +1707,12 @@
   }
 
+  /**
+   * Compute script order depending on dependencies.
+   * Assigned to $script->extra['order'].
+   *
+   * @param string $script_id
+   * @param int $recursion_limiter
+   * @return int
+   */
   private function compute_script_topological_order($script_id, $recursion_limiter=0)
   {
@@ -1591,4 +1735,7 @@
   }
 
+  /**
+   * Callback for scripts sorter.
+   */
   private static function cmp_by_mode_and_order($s1, $s2)
   {
@@ -1608,12 +1755,21 @@
 
 
-/*Allows merging of javascript and css files into a single one.*/
+/**
+ * Allows merging of javascript and css files into a single one.
+ */
 final class FileCombiner
 {
-  private $type; // js or css
+  /** @var string 'js' or 'css' */
+  private $type;
+  /** @var bool */
   private $is_css;
+  /** @var Combinable[] */
   private $combinables;
 
-  function FileCombiner($type, $combinables=array())
+  /**
+   * @param string $type 'js' or 'css'
+   * @param Combinable[] $combinables
+   */
+  function __construct($type, $combinables=array())
   {
     $this->type = $type;
@@ -1622,4 +1778,7 @@
   }
 
+  /**
+   * Deletes all combined files from cache directory.
+   */
   static function clear_combined_files()
   {
@@ -1633,17 +1792,22 @@
   }
 
-  function add($combinables)
-  {
-    if ($combinables instanceof Combinable)
-    {
-      $this->combinables[] = $combinables;
+  /**
+   * @param Combinable|Combinable[] $combinable
+   */
+  function add($combinable)
+  {
+    if (is_array($combinable))
+    {
+      $this->combinables = array_merge($this->combinables, $combinable);
     }
     else
     {
-      foreach($combinables as $combinable)
-        $this->combinables[] = $combinable;
-    }
-  }
-
+      $this->combinables[] = $combinable;
+    }
+  }
+
+  /**
+   * @return Combinable[]
+   */
   function combine()
   {
@@ -1686,4 +1850,12 @@
   }
 
+  /**
+   * Process a set of pending files.
+   *
+   * @param array &$result
+   * @param array &$pending
+   * @param string[] $key
+   * @param bool $force
+   */
   private function flush_pending(&$result, &$pending, $key, $force)
   {
@@ -1716,4 +1888,12 @@
   }
 
+  /**
+   * Process one combinable file.
+   *
+   * @param Combinable $combinable
+   * @param bool $return_content
+   * @param bool $force
+   * @return null|string
+   */
   private function process_combinable($combinable, $return_content, $force)
   {
@@ -1742,5 +1922,5 @@
 
       if ($this->is_css)
-        $content = self::process_css($content, dirname($combinable->path) );
+        $content = self::process_css($content, $combinable->path );
       else
         $content = self::process_js($content, $combinable->path );
@@ -1755,5 +1935,5 @@
       $content = file_get_contents(PHPWG_ROOT_PATH . $combinable->path);
       if ($this->is_css)
-        $content = self::process_css($content, dirname($combinable->path) );
+        $content = self::process_css($content, $combinable->path );
       else
         $content = self::process_js($content, $combinable->path );
@@ -1762,4 +1942,11 @@
   }
 
+  /**
+   * Process a JS file.
+   *
+   * @param string $js file content
+   * @param string $file
+   * @return string
+   */
   private static function process_js($js, $file)
   {
@@ -1772,8 +1959,15 @@
   }
 
-  private static function process_css($css, $dir)
-  {
-    $css = self::process_css_rec($css, $dir);
-    if (version_compare(PHP_VERSION, '5.2.4', '>='))
+  /**
+   * Process a CSS file.
+   *
+   * @param string $css file content
+   * @param string $file
+   * @return string
+   */
+  private static function process_css($css, $file)
+  {
+    $css = self::process_css_rec($css, dirname($file));
+    if (strpos($file, '.min')===false and version_compare(PHP_VERSION, '5.2.4', '>='))
     {
       require_once(PHPWG_ROOT_PATH.'include/cssmin.class.php');
@@ -1784,4 +1978,11 @@
   }
 
+  /**
+   * Resolves relative links in CSS file.
+   *
+   * @param string $css file content
+   * @param string $dir
+   * @return string
+   */
   private static function process_css_rec($css, $dir)
   {
@@ -1817,5 +2018,4 @@
     return $css;
   }
-
 }
 
