Index: media.php
===================================================================
--- media.php	(revision 58844)
+++ media.php	(working copy)
@@ -284,8 +284,16 @@
  * @param int        $width  Optional. Image width in pixels. Default 0.
  * @param int        $height Optional. Image height in pixels. Default 0.
  * @param bool|array $crop   {
- *     Optional. Image cropping behavior. If false, the image will be scaled (default).
- *     If true, image will be cropped to the specified dimensions using center positions.
+ *     Optional. Image cropping behavior. Determines how the image is resized to fit the specified dimensions.
+ *
+ *     If false, the image will be scaled proportionally to fit within the specified dimensions.
+ *     Only one dimension (width or height) is guaranteed to match the specified value, while the other dimension
+ *     will be adjusted to maintain the original aspect ratio.
+ *
+ *     If true, the image will be cropped to exactly match the specified dimensions. Both the width and height
+ *     will be guaranteed to match the specified values, with parts of the image being trimmed if necessary.
+ *     The cropping will use center positions by default.
+ *
  *     If an array, the image will be cropped using the array to specify the crop location:
  *
  *     @type string $0 The x crop position. Accepts 'left', 'center', or 'right'.