-// Scale an image to fit a particular size (such as 'thumb' or 'medium'), and return an image URL, height and width.
-// The URL might be the original image, or it might be a resized version. This function won't create a new resized copy, it will just return an already resized one if it exists.
-// returns an array($url, $width, $height)
+/**
+ * Scale an image to fit a particular size (such as 'thumb' or 'medium').
+ *
+ * Array with image url, width, height, and whether is intermediate size, in
+ * that order is returned on success is returned. $is_intermediate is true if
+ * $url is a resized image, false if it is the original.
+ *
+ * The URL might be the original image, or it might be a resized version. This
+ * function won't create a new resized copy, it will just return an already
+ * resized one if it exists.
+ *
+ * A plugin may use the 'image_downsize' filter to hook into and offer image
+ * resizing services for images. The hook must return an array with the same
+ * elements that are returned in the function. The first element being the URL
+ * to the new image that was resized.
+ *
+ * @since 2.5.0
+ * @uses apply_filters() Calls 'image_downsize' on $id and $size to provide
+ * resize services.
+ *
+ * @param int $id Attachment ID for image.
+ * @param string $size Optional, default is 'medium'. Size of image, can be 'thumbnail'.
+ * @return bool|array False on failure, array on success.
+ */