Index: /trunk/include/derivative.inc.php
===================================================================
--- /trunk/include/derivative.inc.php	(revision 25753)
+++ /trunk/include/derivative.inc.php	(revision 25754)
@@ -20,6 +20,14 @@
 // +-----------------------------------------------------------------------+
 
-/*A source image is used to get a derivative image. A source image is either the original file for a jpg or a
-'representative' image of a non image file or a standard icon for the non-image file.*/
+/**
+ * @package Derivatives
+ */
+
+
+/**
+ * A source image is used to get a derivative image. It is either
+ * the original file for a jpg/png/... or a 'representative' image
+ * of a  non image file or a standard icon for the non-image file.
+ */
 final class SrcImage
 {
@@ -28,12 +36,18 @@
   const DIM_NOT_GIVEN = 0x04;
 
+  /** @var int */
   public $id;
+  /** @var string */
   public $rel_path;
+  /** @var int */
   public $rotation = 0;
-
+  /** @var int[] */
   private $size=null;
+  /** @var int */
   private $flags=0;
 
-  /*@param infos assoc array of data from images table*/
+  /**
+   * @param array $infos assoc array of data from images table
+   */
   function __construct($infos)
   {
@@ -89,4 +103,7 @@
   }
 
+  /**
+   * @return bool
+   */
   function is_original()
   {
@@ -94,4 +111,7 @@
   }
 
+  /**
+   * @return bool
+   */
   function is_mimetype()
   {
@@ -99,4 +119,7 @@
   }
 
+  /**
+   * @return string
+   */
   function get_path()
   {
@@ -104,4 +127,7 @@
   }
 
+  /**
+   * @return string
+   */
   function get_url()
   {
@@ -114,4 +140,7 @@
   }
 
+  /**
+   * @return bool
+   */
   function has_size()
   {
@@ -119,5 +148,7 @@
   }
 
-  /* @return a 2-element array containing width/height or null if dimensions are not available*/
+  /**
+   * @return int[]|null 0=width, 1=height or null if fail to compute size
+   */
   function get_size()
   {
@@ -138,17 +169,27 @@
 
 
-/*Holds information (path, url, dimensions) about a derivative image. A derivative image is constructed from a source
-image (SrcImage class) and derivative parameters (DerivativeParams class).
-*/
+/**
+ * Holds information (path, url, dimensions) about a derivative image.
+ * A derivative image is constructed from a source image (SrcImage class)
+ * and derivative parameters (DerivativeParams class).
+ */
 final class DerivativeImage
 {
+  /** @var SrcImage */
   public $src_image;
-
+  /** @var array */
   private $params;
-  private $rel_path, $rel_url, $is_cached=true;
-
-  /*
-  @param type string of standard derivative param type (e.g. IMG_???) or a DerivativeParams object
-  @param src_image the source image of this derivative*/
+  /** @var string */
+  private $rel_path;
+  /** @var string */
+  private $rel_url;
+  /** @var bool */
+  private $is_cached=true;
+
+  /**
+   * @param string|DerivativeParams $type standard derivative param type (e.g. IMG_*)
+   *    or a DerivativeParams object
+   * @param SrcImage $src_image the source image of this derivative
+   */
   function __construct($type, SrcImage $src_image)
   {
@@ -166,4 +207,10 @@
   }
 
+  /**
+   * Generates the url of a thumbnail.
+   *
+   * @param array|SrcImage $infos array of info from db or SrcImage
+   * @return string
+   */
   static function thumb_url($infos)
   {
@@ -172,8 +219,11 @@
 
   /**
-  @return derivative image url
-  @param type string of standard derivative param type (e.g. IMG_???) or a DerivativeParams object
-  @param infos assoc array of data from images table or a SrcImage object
-  */
+   * Generates the url for a particular photo size.
+   *
+   * @param string|DerivativeParams $type standard derivative param type (e.g. IMG_*)
+   *    or a DerivativeParams object
+   * @param array|SrcImage $infos array of info from db or SrcImage
+   * @return string
+   */
   static function url($type, $infos)
   {
@@ -194,5 +244,5 @@
   /**
    * Return associative an array of all DerivativeImage for a specific image.
-   * Disabled derivative types can be still found in the return mapped to an
+   * Disabled derivative types can be still found in the return, mapped to an
    * enabled derivative (e.g. the values are not unique in the return array).
    * This is useful for any plugin/theme to just use $deriv[IMG_XLARGE] even if 
@@ -229,5 +279,5 @@
    * Disabled derivatives fallback to an enabled derivative.
    *
-   * @param string $type
+   * @param string $type standard derivative param type (e.g. IMG_*)
    * @param array|SrcImage $src_image array of info from db or SrcImage
    * @return DerivativeImage|null null if $type not found
@@ -255,4 +305,7 @@
   }
 
+  /**
+   * @todo : documentation of DerivativeImage::build
+   */
   private static function build($src, &$params, &$rel_path, &$rel_url, &$is_cached=null)
   {
@@ -335,4 +388,7 @@
   }
 
+  /**
+   * @return string
+   */
   function get_path()
   {
@@ -340,4 +396,7 @@
   }
 
+  /**
+   * @return string
+   */
   function get_url()
   {
@@ -353,4 +412,7 @@
   }
 
+  /**
+   * @return bool
+   */
   function same_as_source()
   {
@@ -358,5 +420,7 @@
   }
 
-
+  /**
+   * @return string one if IMG_* or 'Original'
+   */
   function get_type()
   {
@@ -366,5 +430,7 @@
   }
 
-  /* returns the size of the derivative image*/
+  /**
+   * @return int[]
+   */
   function get_size()
   {
@@ -376,4 +442,9 @@
   }
 
+  /**
+   * Returns the size as CSS rule.
+   *
+   * @return string
+   */
   function get_size_css()
   {
@@ -385,4 +456,9 @@
   }
 
+  /**
+   * Returns the size as HTML attributes.
+   *
+   * @return string
+   */
   function get_size_htm()
   {
@@ -394,4 +470,9 @@
   }
 
+  /**
+   * Returns literal size: $widthx$height.
+   *
+   * @return string
+   */
   function get_size_hr()
   {
@@ -403,4 +484,9 @@
   }
 
+  /**
+   * @param int $maxw
+   * @param int $mawh
+   * @return int[]
+   */
   function get_scaled_size($maxw, $maxh)
   {
@@ -427,4 +513,11 @@
   }
 
+  /**
+   * Returns the scaled size as HTML attributes.
+   *
+   * @param int $maxw
+   * @param int $mawh
+   * @return string
+   */
   function get_scaled_size_htm($maxw=9999, $maxh=9999)
   {
@@ -436,4 +529,7 @@
   }
 
+  /**
+   * @return bool
+   */
   function is_cached()
   {
Index: /trunk/include/derivative_params.inc.php
===================================================================
--- /trunk/include/derivative_params.inc.php	(revision 25753)
+++ /trunk/include/derivative_params.inc.php	(revision 25754)
@@ -20,4 +20,15 @@
 // +-----------------------------------------------------------------------+
 
+/**
+ * @package Derivatives
+ */
+
+
+/**
+ * Formats a size name into a 2 chars identifier usable in filename.
+ *
+ * @param string $t one of IMG_*
+ * @return string
+ */
 function derivative_to_url($t)
 {
@@ -25,4 +36,10 @@
 }
 
+/**
+ * Formats a size array into a identifier usable in filename.
+ *
+ * @param int[] $s
+ * @return string
+ */
 function size_to_url($s)
 {
@@ -34,4 +51,9 @@
 }
 
+/**
+ * @param int[] $s1
+ * @param int[] $s2
+ * @return bool
+ */
 function size_equals($s1, $s2)
 {
@@ -39,4 +61,10 @@
 }
 
+/**
+ * Converts a char a-z into a float.
+ *
+ * @param string
+ * @return float
+ */
 function char_to_fraction($c)
 {
@@ -44,4 +72,10 @@
 }
 
+/**
+ * Converts a float into a char a-z.
+ *
+ * @param float
+ * @return string
+ */
 function fraction_to_char($f)
 {
@@ -49,9 +83,21 @@
 }
 
-/** small utility to manipulate a 'rectangle'*/
+
+/**
+ * Small utility to manipulate a 'rectangle'.
+ */
 final class ImageRect
 {
+  /**
+   * @var int $l
+   * @var int $t
+   * @var int $r
+   * @var int $b
+   */
   public $l,$t,$r,$b;
 
+  /**
+   * @param int[] $l width and height
+   */
   function __construct($l)
   {
@@ -61,4 +107,7 @@
   }
 
+  /**
+   * @return int
+   */
   function width()
   {
@@ -66,4 +115,7 @@
   }
 
+  /**
+   * @return int
+   */
   function height()
   {
@@ -71,7 +123,10 @@
   }
 
-  /** crops horizontally this rectangle by increasing left side and/or reducing the right side.
-  @param pixels the amount to substract from the width
-  @param coi a 4 character string (or null) containing the center of interest*/
+  /**
+   * Crops horizontally this rectangle by increasing left side and/or reducing the right side.
+   *
+   * @param int $pixels - the amount to substract from the width
+   * @param stirng $coi - a 4 character string (or null) containing the center of interest
+   */
   function crop_h($pixels, $coi)
   {
@@ -102,7 +157,10 @@
   }
 
-  /** crops vertically this rectangle by increasing top side and/or reducing the bottom side.
-  @param pixels the amount to substract from the height
-  @param coi a 4 character string (or null) containing the center of interest*/
+  /**
+   * Crops vertically this rectangle by increasing top side and/or reducing the bottom side.
+   *
+   * @param int $pixels - the amount to substract from the height
+   * @param string $coi - a 4 character string (or null) containing the center of interest
+   */
   function crop_v($pixels, $coi)
   {
@@ -132,23 +190,40 @@
     $this->b -= $pixels - $tlcrop;
   }
-
-}
-
-
-/** Paramaters for derivative scaling and cropping. Instance of this class contained by DerivativeParams class.*/
+}
+
+
+/**
+ * Paramaters for derivative scaling and cropping.
+ * Instance of this class contained by DerivativeParams class.
+ */
 final class SizingParams
 {
-  /**
-  @param ideal_size two element array of maximum output dimensions (width, height)
-  @param max_crop range 0=no cropping ... 1= max cropping (100% of width/height); expressed as a factor of the input width/height
-  @param min_size used only if max_crop != 0 - two element array of output dimensions (width, height)
-  */
-  function __construct($ideal_size, $max_crop = 0, $min_size = null)
+  /** @var int[] */
+  var $ideal_size;
+  /** @var float */
+  var $max_crop;
+  /** @var int[] */
+  var $min_size;
+
+  /**
+   * @param int[] $ideal_size - two element array of maximum output dimensions (width, height)
+   * @param float $max_crop - from 0=no cropping to 1= max cropping (100% of width/height);
+   *    expressed as a factor of the input width/height
+   * @param int[] $min_size - (used only if _$max_crop_ !=0) two element array of output dimensions (width, height)
+   */
+  function __construct($ideal_size, $max_crop=0, $min_size=null)
   {
     $this->ideal_size = $ideal_size;
-    $this->max_crop = $max_crop; // range 0=no cropping ... 1= max cropping (100% of width/height)
+    $this->max_crop = $max_crop;
     $this->min_size = $min_size;
   }
 
+  /**
+   * Returns a simple SizingParams object.
+   *
+   * @param int $w
+   * @param int $h
+   * @return SizingParams
+   */
   static function classic($w, $h)
   {
@@ -156,4 +231,10 @@
   }
 
+  /**
+   * Returns a square SizingParams object.
+   *
+   * @param int $x
+   * @return SizingParams
+   */
   static function square($w)
   {
@@ -161,4 +242,9 @@
   }
 
+  /**
+   * Adds tokens depending on sizing configuration.
+   *
+   * @param array &$tokens
+   */
   function add_url_tokens(&$tokens)
   {
@@ -179,10 +265,12 @@
   }
 
-  /* calculate the cropping rectangle and the scaled size for an input image size
-  @param in_size two element array of input dimensions (width, height)
-  @param coi empty or a four character encoded string containing the center of interest (unused if max_crop=0)
-  @param crop_rect output ImageRect containing the cropping rectangle or null if cropping is not required
-  @param scale_size output two element array containing width and height of the scaled image
-  */
+  /**
+   * Calculates the cropping rectangle and the scaled size for an input image size.
+   *
+   * @param int[] $in_size - two element array of input dimensions (width, height)
+   * @param string $coi - four character encoded string containing the center of interest (unused if max_crop=0)
+   * @param ImageRect &$crop_rect - ImageRect containing the cropping rectangle or null if cropping is not required
+   * @param int[] &$scale_size - two element array containing width and height of the scaled image
+   */
   function compute($in_size, $coi, &$crop_rect, &$scale_size)
   {
@@ -246,17 +334,26 @@
     }
   }
-
-}
-
-
-/** All needed parameters to generate a derivative image.*/
+}
+
+
+/**
+ * All needed parameters to generate a derivative image.
+ */
 final class DerivativeParams
 {
-  public $type = IMG_CUSTOM; // string IMG_xxx
-  public $last_mod_time = 0; // used for non-custom images to regenerate the cached files
+  /** @var SizingParams */
+  public $sizing;
+  /** @var string among IMG_* */
+  public $type = IMG_CUSTOM;
+  /** @var int used for non-custom images to regenerate the cached files */
+  public $last_mod_time = 0;
+  /** @var bool */
   public $use_watermark = false;
-  public $sizing; // of type SizingParams
-  public $sharpen = 0; // range 0= no sharpening ... 1= max sharpening
-
+  /** @var float from 0=no sharpening to 1=max sharpening */
+  public $sharpen = 0;
+
+  /**
+   * @param SizingParams $sizing
+   */
   function __construct($sizing)
   {
@@ -264,9 +361,17 @@
   }
 
+  /**
+   * @return array
+   */
   public function __sleep()
   {
-      return array('last_mod_time', 'sizing', 'sharpen');
-  }
-
+    return array('last_mod_time', 'sizing', 'sharpen');
+  }
+
+  /**
+   * Adds tokens depending on sizing configuration.
+   *
+   * @param array &$tokens
+   */
   function add_url_tokens(&$tokens)
   {
@@ -274,4 +379,7 @@
   }
 
+  /**
+   * @return int[]
+   */
   function compute_final_size($in_size)
   {
@@ -280,4 +388,7 @@
   }
 
+  /**
+   * @return int
+   */
   function max_width()
   {
@@ -285,4 +396,7 @@
   }
 
+  /**
+   * @return int
+   */
   function max_height()
   {
@@ -290,4 +404,9 @@
   }
 
+  /**
+   * @todo : description of DerivativeParams::is_identity
+   *
+   * @return bool
+   */
   function is_identity($in_size)
   {
@@ -300,4 +419,7 @@
   }
 
+  /**
+   * @return bool
+   */
   function will_watermark($out_size)
   {
@@ -311,3 +433,4 @@
   }
 }
+
 ?>
Index: /trunk/include/derivative_std_params.inc.php
===================================================================
--- /trunk/include/derivative_std_params.inc.php	(revision 25753)
+++ /trunk/include/derivative_std_params.inc.php	(revision 25754)
@@ -20,4 +20,9 @@
 // +-----------------------------------------------------------------------+
 
+/**
+ * @package Derivatives
+ */
+
+
 define('IMG_SQUARE', 'square');
 define('IMG_THUMB', 'thumb');
@@ -31,27 +36,51 @@
 define('IMG_CUSTOM', 'custom');
 
+
+/**
+ * Container for watermark configuration.
+ */
 final class WatermarkParams
 {
+  /** @var string */
   public $file = '';
+  /** @var int[] */
   public $min_size = array(500,500);
+  /** @var int */
   public $xpos = 50;
+  /** @var int */
   public $ypos = 50;
+  /** @var int */
   public $xrepeat = 0;
+  /** @var int */
   public $opacity = 100;
 }
 
 
+/**
+ * Container for standard derivatives parameters.
+ */
 final class ImageStdParams
 {
+  /** @var string[] */
   private static $all_types = array(
-    IMG_SQUARE,IMG_THUMB,IMG_XXSMALL,IMG_XSMALL,IMG_SMALL,IMG_MEDIUM,IMG_LARGE,IMG_XLARGE,IMG_XXLARGE
+    IMG_SQUARE, IMG_THUMB, IMG_XXSMALL, IMG_XSMALL, IMG_SMALL,
+    IMG_MEDIUM, IMG_LARGE, IMG_XLARGE, IMG_XXLARGE
     );
+  /** @var DerivativeParams[] */
   private static $all_type_map = array();
+  /** @var DerivativeParams[] */
   private static $type_map = array();
+  /** @var DerivativeParams[] */
   private static $undefined_type_map = array();
+  /** @var WatermarkParams */
   private static $watermark;
+  /** @var array */
   public static $custom = array();
+  /** @var int */
   public static $quality=95;
 
+  /**
+   * @return string[]
+   */
   static function get_all_types()
   {
@@ -59,4 +88,7 @@
   }
 
+  /**
+   * @return DerivativeParams[]
+   */
   static function get_all_type_map()
   {
@@ -64,4 +96,7 @@
   }
 
+  /**
+   * @return DerivativeParams[]
+   */
   static function get_defined_type_map()
   {
@@ -69,4 +104,7 @@
   }
 
+  /**
+   * @return DerivativeParams[]
+   */
   static function get_undefined_type_map()
   {
@@ -74,4 +112,7 @@
   }
 
+  /**
+   * @return DerivativeParams
+   */
   static function get_by_type($type)
   {
@@ -79,4 +120,12 @@
   }
 
+  /**
+   * @param int $w
+   * @param int $h
+   * @param float $crop
+   * @param int $minw
+   * @param int $minh
+   * @return DerivativeParams
+   */
   static function get_custom($w, $h, $crop=0, $minw=null, $minh=null)
   {
@@ -95,4 +144,7 @@
   }
 
+  /**
+   * @return WatermarkParams
+   */
   static function get_watermark()
   {
@@ -100,4 +152,7 @@
   }
 
+  /**
+   * Loads derivative configuration from database or initializes it.
+   */
   static function load_from_db()
   {
@@ -122,4 +177,7 @@
   }
 
+  /**
+   * @param WatermarkParams $watermark
+   */
   static function set_watermark($watermark)
   {
@@ -127,4 +185,9 @@
   }
 
+  /**
+   * @see ImageStdParams::save()
+   *
+   * @param DerivativeParams[] $map
+   */
   static function set_and_save($map)
   {
@@ -134,4 +197,7 @@
   }
 
+  /**
+   * Saves the configuration in database.
+   */
   static function save()
   {
@@ -147,4 +213,7 @@
   }
 
+  /**
+   * @return DerivativeParams[]
+   */
   static function get_default_sizes()
   {
@@ -160,11 +229,17 @@
       IMG_XXLARGE => new DerivativeParams( SizingParams::classic(1656,1242) ),
     );
+    $now = time();
     foreach($arr as $params)
     {
-      $params->last_mod_time = time();
+      $params->last_mod_time = $now;
     }
     return $arr;
   }
 
+  /**
+   * Compute 'apply_watermark'
+   *
+   * @param DerivativeParams $params
+   */
   static function apply_global($params)
   {
@@ -174,4 +249,7 @@
   }
 
+  /**
+   * Build 'type_map', 'all_type_map' and 'undefined_type_map'.
+   */
   private static function build_maps()
   {
@@ -201,5 +279,4 @@
     }
   }
-
 }
 
