Add doc comments to image related classes (#1146)

app/code/core/Mage/Catalog/Model/Product/Image.php

@@ -35,20 +35,70 @@
  */
 class Mage_Catalog_Model_Product_Image extends Mage_Core_Model_Abstract
 {
+    /**
+     * Requested width for the scaled image
+     *
+     * @var int
+     */
     protected $_width;
+
+    /**
+     * Requested height for the scaled image
+     *
+     * @var int
+     */
     protected $_height;
     protected $_quality = 90;
 
+    /**
+     * @var bool
+     */
     protected $_keepAspectRatio  = true;
     protected $_keepFrame        = true;
+
+    /**
+     * If set to true and image format supports transparency (e.g. PNG),
+     * transparency will be kept in scaled images. Otherwise transparent areas will be changed to $_backgroundColor
+     * @var bool
+     */
     protected $_keepTransparency = true;
+
+    /**
+     *  If true, images will not be scaled up (when original image is smaller then requested size)
+     *
+     * @var bool
+     */
     protected $_constrainOnly    = false;
+
+    /**
+     * Array with RGB values for background color e.g. [255, 255, 255]
+     * used e.g. when filling transparent color in scaled images
+     *
+     * @var array
+     */
     protected $_backgroundColor  = array(255, 255, 255);
 
+    /**
+     * Absolute path to and original (full resolution) image
+     *
+     * @var string
+     */
     protected $_baseFile;
     protected $_isBaseFilePlaceholder;
+
+    /**
+     * @var string Absolute path to scaled/transformed image
+     */
     protected $_newFile;
+
+    /**
+     * @var Varien_Image
+     */
     protected $_processor;
+
+    /**
+     * @var string e.g. "small_image"
+     */
     protected $_destinationSubdir;
     protected $_angle;
 
@@ -349,7 +399,7 @@ public function setBaseFile($file)
             $path[] = "{$this->_width}x{$this->_height}";
         }
 
-        // add misk params as a hash
+        // add misc params as a hash
         $miscParams = array(
                 ($this->_keepAspectRatio  ? '' : 'non') . 'proportional',
                 ($this->_keepFrame        ? '' : 'no')  . 'frame',

lib/Varien/Image.php

@@ -33,8 +33,16 @@
  */
 class Varien_Image
 {
+    /**
+     * @var Varien_Image_Adapter_Abstract|Varien_Image_Adapter_Gd2
+     */
     protected $_adapter;
 
+    /**
+     * Absolute path to an image
+     *
+     * @var string
+     */
     protected $_fileName;
 
     /**

lib/Varien/Image/Adapter/Abstract.php

@@ -32,6 +32,10 @@
 abstract class Varien_Image_Adapter_Abstract
 {
     public $fileName = null;
+
+    /**
+     * @var int Color used to fill space when rotating image, do not confuse it with $_backgroundColor
+     */
     public $imageBackgroundColor = 0;
 
     const POSITION_TOP_LEFT = 'top-left';
@@ -42,13 +46,66 @@ abstract class Varien_Image_Adapter_Abstract
     const POSITION_TILE = 'tile';
     const POSITION_CENTER = 'center';
 
+    /**
+     * Image file type of the image $this->_fileName
+     * e.g 2 for IMAGETYPE_JPEG
+     *
+     * @var int
+     */
     protected $_fileType = null;
+
+    /**
+     * Absolute path to an original image
+     *
+     * @var string
+     */
     protected $_fileName = null;
+
+    /**
+     * Image mime type e.g. image/jpeg
+     *
+     * @var string
+     */
     protected $_fileMimeType = null;
+
+    /**
+     * Image file name (without path, with extension)
+     *
+     * @var string
+     */
     protected $_fileSrcName = null;
+
+    /**
+     * Absolute path to a folder containing original image
+     *
+     * @var string
+     */
     protected $_fileSrcPath = null;
+
+    /**
+     * Image resource created e.g. using imagecreatefromjpeg
+     * This resource is being processed, so after open() it contains
+     * original image, but after resize() it's already a scaled version.
+     *
+     * @see Varien_Image_Adapter_Gd2::open()
+     * @var resource
+     */
     protected $_imageHandler = null;
+
+    /**
+     * Width of the image stored in $_imageHandler
+     *
+     * @see getMimeType
+     * @var string|int
+     */
     protected $_imageSrcWidth = null;
+
+    /**
+     * Height of the image stored in $_imageHandler
+     *
+     * @see getMimeType
+     * @var string|int
+     */
     protected $_imageSrcHeight = null;
     protected $_requiredExtensions = null;
     protected $_watermarkPosition = null;
@@ -59,8 +116,24 @@ abstract class Varien_Image_Adapter_Abstract
 
     protected $_keepAspectRatio;
     protected $_keepFrame;
+
+    /**
+     * @var bool If set to true and image format supports transparency (e.g. PNG),
+     * transparency will be kept in scaled images. Otherwise transparent areas will be changed to $_backgroundColor
+     */
     protected $_keepTransparency;
+
+    /**
+     * Array with RGB values for background color e.g. [255, 255, 255]
+     * used e.g. when filling transparent color in scaled images
+     *
+     * @var array
+     */
     protected $_backgroundColor;
+
+    /**
+     * @var bool If true, images will not be scaled up (when original image is smaller then requested size)
+     */
     protected $_constrainOnly;
 
     abstract public function open($fileName);
@@ -161,7 +234,7 @@ public function getWatermarkHeigth()
      * Get/set keepAspectRatio
      *
      * @param bool $value
-     * @return bool|Varien_Image_Adapter_Abstract
+     * @return bool
      */
     public function keepAspectRatio($value = null)
     {
@@ -246,7 +319,7 @@ public function backgroundColor($value = null)
             }
             $this->_backgroundColor = $value;
         }
-        
+
         return $this->_backgroundColor;
     }