Index: imageapi.module
===================================================================
RCS file: /cvs/drupal-contrib/contributions/modules/imageapi/imageapi.module,v
retrieving revision 1.17
diff -u -p -r1.17 imageapi.module
--- imageapi.module	29 May 2008 02:47:01 -0000	1.17
+++ imageapi.module	29 May 2008 04:11:25 -0000
@@ -1,5 +1,5 @@
 <?php
-// $Id: imageapi.module,v 1.17 2008/05/29 02:47:01 drewish Exp $
+// $Id: imageapi.module,v 1.16 2008/04/30 15:42:40 dopry Exp $
 
 /**
  * @file
@@ -16,6 +16,9 @@
  *
  */
 
+/**
+ * Implementation of hook_menu().
+ */
 function imageapi_menu() {
   $items = array();
   $items['admin/settings/imageapi'] = array(
@@ -147,7 +150,7 @@ function imageapi_default_toolkit() {
  * @param $height
  *   The target height in pixels.
  * @return
- *   Modified ImageAPI Image object.
+ *   True or false, based on success.
  */
 function imageapi_image_scale_and_crop(&$image, $width, $height) {
   $aspect = $image->info['height'] / $image->info['width'];
@@ -179,7 +182,7 @@ function imageapi_image_scale_and_crop(&
  * @param $upscale
  *   Allow upscaling.
  * @return
- *   true or false, based on success.
+ *   True or false, based on success.
  */
 function imageapi_image_scale(&$image, $width, $height, $upscale = false) {
   // set width/height according to aspect ratio if either is empty;
@@ -218,7 +221,7 @@ function imageapi_image_scale(&$image, $
  * @param $toolkit
  *   An optional override of the default image toolkit.
  * @return
- *   true or false, based on success.
+ *   True or false, based on success.
  */
 function imageapi_image_resize(&$image, $width, $height) {
   return call_user_func($image->toolkit .'_image_resize', $image, $width, $height);
@@ -227,20 +230,16 @@ function imageapi_image_resize(&$image, 
 /**
  * Rotate an image by the given number of degrees.
  *
- * @param $source
- *   The filepath of the source image.
- * @param $destination
- *   The file path of the destination image.
+ * @param $image
+ *   An imageapi image object returned by imageapi_image_open().
  * @param $degrees
  *   The number of (clockwise) degrees to rotate the image.
  * @param $bg_color
  *   An hexidecimal integer specifying the background color to use for the
  *   uncovered area of the image after the rotation. E.g. 0x000000 for black,
  *   0xff00ff for magenta, and 0xffffff for white.
- * @param $toolkit
- *   An optional override of the default image toolkit.
  * @return
- *   true or false, based on success.
+ *   True or false, based on success.
  */
 function imageapi_image_rotate(&$image, $degrees, $bgcolor = 0x000000) {
   return call_user_func($image->toolkit .'_image_rotate', $image, $degrees, $bgcolor);
@@ -250,7 +249,7 @@ function imageapi_image_rotate(&$image, 
  * Crop an image to the rectangle specified by the given rectangle.
  *
  * @param $image
- *   An imageapi image object.
+ *   An imageapi image object returned by imageapi_image_open().
  * @param $x
  *   The top left co-ordinate of the crop area (x axis value).
  * @param $y
@@ -260,7 +259,7 @@ function imageapi_image_rotate(&$image, 
  * @param $height
  *   The target height in pixels.
  * @return
- *   modifed image object.
+ *   True or false, based on success.
  */
 function imageapi_image_crop(&$image, $x, $y, $width, $height) {
   $aspect = $image->info['height'] / $image->info['width'];
@@ -270,11 +269,29 @@ function imageapi_image_crop(&$image, $x
   return call_user_func($image->toolkit .'_image_crop', $image, $x, $y, $width, $height);
 }
 
-
+/**
+ * Convert an image to grayscale.
+ *
+ * @param $image
+ *   An imageapi image object returned by imageapi_image_open().
+ * @return
+ *   True or false, based on success.
+ */
 function imageapi_image_desaturate(&$image) {
   return call_user_func($image->toolkit .'_image_desaturate', $image);
 }
 
+/**
+ * Open an image file and return an imageapi image object. Any changes to the
+ * file are not saved until imageapi_image_close() is called.
+ *
+ * @param $file 
+ *   Path to an image file.
+ * @param $toolkit
+ *   An optional, image toolkit name to override the default.
+ * @return
+ *   ImageAPI Image object or FALSE if there was a problem opening the file.
+ */
 function imageapi_image_open($file, $toolkit = false) {
   if (!$toolkit) {
     $toolkit = imageapi_default_toolkit();
@@ -293,14 +310,14 @@ function imageapi_image_open($file, $too
 }
 
 /**
- * Write an image to a file. 
+ * Close the image and save the changes to a file.
  *
  * @param $image 
  *   imageAPI image object.
  *
  * @param $destination
- *   destination path where image should be saved. If it is empty the original image will
- *   be overwritten.
+ *   Destination path where the image should be saved. If it is empty the
+ *   original image file will be overwritten.
  */
 function imageapi_image_close($image, $destination = '') {
   if (empty($destination)) {
@@ -317,9 +334,14 @@ function imageapi_image_close($image, $d
 
 
 /**
- * Convert a hex string to it's rgba integer components
- * $hex can be in the formats: '#ABC','ABC','#ABCD','ABCD','#AABBCC','AABBCC','#AABBCCDD','AABBCCDD'
+ * Convert a hex string to its RGBA (Red, Green, Blue, Alpha) integer
+ * components.
  *
+ * @param $hex 
+ *   A string specifing an RGB color in the formats:
+ *   '#ABC','ABC','#ABCD','ABCD','#AABBCC','AABBCC','#AABBCCDD','AABBCCDD'
+ * @return
+ *   An array with four elements for red, green, blue, and alpha.
  */
 function imageapi_hex2rgba($hex) {
   $hex = ltrim($hex, '#');