Ticket #7658: 7658.r8921.diff

media.php

@@ -53 +53 @@
                 // if no width is set, default to the theme content width if available
         }
         elseif ( $size == 'large' ) {
-                // we're inserting a large size image into the editor.  if it's a really big image we'll scale it down to fit reasonably
-                // within the editor itself, and within the theme's content width if it's known.  the user can resize it in the editor
-                // if they wish.
+                // we're inserting a large size image into the editor.  if it's a really
+                // big image we'll scale it down to fit reasonably within the editor
+                // itself, and within the theme's content width if it's known.  the user
+                // can resize it in the editor if they wish.
                 $max_width = intval(get_option('large_size_w'));
                 $max_height = intval(get_option('large_size_h'));
                 if ( intval($content_width) > 0 )
@@ -109 +110 @@
  * 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. Should return true if resizes.
+ *              resize services.
  *
  * @param int $id Attachment ID for image.
  * @param string $size Optional, default is 'medium'. Size of image, can be 'thumbnail'.
@@ -166 +172 @@
 /**
  * An <img src /> tag for an image attachment, scaling it down if requested.
  *
- * {@internal Missing Long Description}}
+ * The filter 'get_image_tag_class' allows for changing the class name for the
+ * image without having to use regular expressions on the HTML content. The
+ * parameters are: what WordPress will use for the class, the Attachment ID,
+ * image align value, and the size the image should be.
  *
+ * The second filter 'get_image_tag' has the HTML content, which can then be
+ * further manipulated by a plugin to change all attribute values and even HTML
+ * content.
+ *
  * @since 2.5.0
  *
  * @uses apply_filters() The 'get_image_tag_class' filter is the IMG element
@@ -197 +210 @@
         return $html;
 }
 
-// same as wp_shrink_dimensions, except the max parameters are optional.
-// if either width or height are empty, no constraint is applied on that dimension.
+/**
+ * Calculates the new dimentions for a downsampled image.
+ *
+ * Same as {@link wp_shrink_dimensions()}, except the max parameters are
+ * optional. If either width or height are empty, no constraint is applied on
+ * that dimension.
+ *
+ * @since 2.5.0
+ *
+ * @param int $current_width Current width of the image.
+ * @param int $current_height Current height of the image.
+ * @param int $max_width Optional. Maximum wanted width.
+ * @param int $max_height Optional. Maximum wanted height.
+ * @return array First item is the width, the second item is the height.
+ */
 function wp_constrain_dimensions( $current_width, $current_height, $max_width=0, $max_height=0 ) {
         if ( !$max_width and !$max_height )
                 return array( $current_width, $current_height );
@@ -217 +243 @@
         return array( intval($current_width * $ratio), intval($current_height * $ratio) );
 }
 
-// calculate dimensions and coordinates for a resized image that fits within a specified width and height
-// if $crop is true, the largest matching central portion of the image will be cropped out and resized to the required size
+/**
+ * Retrieve calculated resized dimensions for use in imagecopyresampled().
+ *
+ * Calculate dimensions and coordinates for a resized image that fits within a
+ * specified width and height. If $crop is true, the largest matching central
+ * portion of the image will be cropped out and resized to the required size.
+ *
+ * @since 2.5.0
+ *
+ * @param int $orig_w Original width.
+ * @param int $orig_h Original height.
+ * @param int $dest_w New width.
+ * @param int $dest_h New height.
+ * @param bool $crop Optional, default is false. Whether to crop image or resize.
+ * @return bool|array False, on failure. Returned array matches parameters for imagecopyresampled() PHP function.
+ */
 function image_resize_dimensions($orig_w, $orig_h, $dest_w, $dest_h, $crop=false) {
 
         if ($orig_w <= 0 || $orig_h <= 0)
@@ -271 +311 @@
 /**
  * Scale down an image to fit a particular size and save a new copy of the image.
  *
- * @param unknown_type $file
- * @param unknown_type $max_w
- * @param unknown_type $max_h
- * @param unknown_type $crop
- * @param unknown_type $suffix
- * @param unknown_type $dest_path
- * @param unknown_type $jpeg_quality
- * @return unknown
+ * The PNG transparency will be preserved using the function, as well as the
+ * image type. If the file going in is PNG, then the resized image is going to
+ * be PNG. The only supported image types are PNG, GIF, and JPEG.
+ *
+ * Some functionality requires API to exist, so some PHP version may lose out
+ * support. This is not the fault of WordPress (where functionality is
+ * downgraded, not actual defects), but of your PHP version.
+ *
+ * @since 2.5.0
+ *
+ * @param string $file Image file path.
+ * @param int $max_w Maximum width to resize to.
+ * @param int $max_h Maximum height to resize to.
+ * @param bool $crop Optional. Whether to crop image or resize.
+ * @param string $suffix Optional. File Suffix.
+ * @param string $dest_path Optional. New image file path.
+ * @param int $jpeg_quality Optional, default is 90. Image quality percentage.
+ * @return mixed WP_Error on failure. String with new destination path. Array of dimensions from {@link image_resize_dimensions()}
  */
 function image_resize( $file, $max_w, $max_h, $crop=false, $suffix=null, $dest_path=null, $jpeg_quality=90) {
 
@@ -342 +392 @@
         return $destfilename;
 }
 
-// resize an image to make a thumbnail or intermediate size, and return metadata describing the new copy
-// returns false if no image was created
+/**
+ * Resize an image to make a thumbnail or intermediate size.
+ *
+ * The returned array has the file size, the image width, and image height. The
+ * filter 'image_make_intermediate_size' can be used to hook in and change the
+ * values of the returned array. The only parameter is the resized file path.
+ *
+ * @since 2.5.0
+ *
+ * @param string $file File path.
+ * @param int $width Image width.
+ * @param int $height Image height.
+ * @param bool $crop Optional, default is false. Whether to crop image to specified height and width or resize.
+ * @return bool|array False, if no image was created. Metadata array on success.
+ */
 function image_make_intermediate_size($file, $width, $height, $crop=false) {
         if ( $width || $height ) {
                 $resized_file = image_resize($file, $width, $height, $crop);
@@ -359 +422 @@
         return false;
 }
 
+/**
+ * Retrieve the image's intermediate size (resized) path, width, and height.
+ *
+ * The $size parameter can be an array with the width and height respectively.
+ * If the size matches the 'sizes' metadata array for width and height, then it
+ * will be used. If there is no direct match, then the nearest image size larger
+ * than the specified size will be used. If nothing is found, then the function
+ * will break out and return false.
+ * 
+ * The metadata 'sizes' is used for compatible sizes that can be used for the
+ * parameter $size value.
+ *
+ * The url path will be given, when the $size parameter is a string.
+ *
+ * @since 2.5.0
+ *
+ * @param int $post_id Attachment ID for image.
+ * @param array|string $size Optional, default is 'thumbnail'. Size of image, either array or string.
+ * @return bool|array False on failure or array of file path, width, and height on success.
+ */
 function image_get_intermediate_size($post_id, $size='thumbnail') {
         if ( !is_array( $imagedata = wp_get_attachment_metadata( $post_id ) ) )
                 return false;
@@ -402 +485 @@
         return $data;
 }
 
-// get an image to represent an attachment - a mime icon for files, thumbnail or intermediate size for images
-// returns an array (url, width, height), or false if no image is available
+/**
+ * Retrieve an image to represent an attachment.
+ *
+ * A mime icon for files, thumbnail or intermediate size for images.
+ *
+ * @since 2.5.0
+ *
+ * @param int $attachment_id Image attachment ID.
+ * @param string $size Optional, default is 'thumbnail'.
+ * @param bool $icon Optional, default is false. Whether it is an icon.
+ * @return bool|array Returns an array (url, width, height), or false, if no image is available.
+ */
 function wp_get_attachment_image_src($attachment_id, $size='thumbnail', $icon = false) {
 
         // get a thumbnail or intermediate image if there is one
@@ -420 +513 @@
         return false;
 }
 
-// as per wp_get_attachment_image_src, but returns an <img> tag
-function wp_get_attachment_image($attachment_id, $size='thumbnail', $icon = false) {
+/**
+ * Retrieve img HTML content for an image to represent an attachment.
+ *
+ * @see wp_get_attachment_image_src() Returns img HTML element based on array.
+ * @since 2.5.0
+ *
+ * @param int $attachment_id Image attachment ID.
+ * @param string $size Optional, default is 'thumbnail'.
+ * @param bool $icon Optional, default is false. Whether it is an icon.
+ * @return string HTML img element or empty string on failure.
+ */
+function wp_get_attachment_image($attachment_id, $size = 'thumbnail', $icon = false) {
 
         $html = '';
         $image = wp_get_attachment_image_src($attachment_id, $size, $icon);
@@ -439 +542 @@
 add_shortcode('wp_caption', 'img_caption_shortcode');
 add_shortcode('caption', 'img_caption_shortcode');
 
+/**
+ * The Caption shortcode.
+ *
+ * Allows a plugin to replace the content that would otherwise be returned. The
+ * filter is 'img_caption_shortcode' and passes an empty string, the attr
+ * parameter and the content parameter values.
+ *
+ * The supported attributes for the shortcode are 'id', 'align', 'width', and
+ * 'caption'.
+ *
+ * @since 2.6.0
+ *
+ * @param array $attr Attributes attributed to the shortcode.
+ * @param string $content Optional. Shortcode content.
+ * @return string
+ */
 function img_caption_shortcode($attr, $content = null) {
 
         // Allow plugins/themes to override the default caption template.
@@ -464 +583 @@
 
 add_shortcode('gallery', 'gallery_shortcode');
 
+/**
+ * The Gallery shortcode.
+ *
+ * This implements the functionality of the Gallery Shortcode for displaying
+ * WordPress images on a post.
+ *
+ * @since 2.5.0
+ *
+ * @param array $attr Attributes attributed to the shortcode.
+ * @return string HTML content to display gallery.
+ */
 function gallery_shortcode($attr) {
         global $post;
 
@@ -596 +726 @@
                 echo wp_get_attachment_link($attachments[$k]->ID, 'thumbnail', true);
 }
 
+/**
+ * Retrieve taxonomies attached to the attachment.
+ *
+ * @since 2.5.0
+ *
+ * @param int|array|object $attachment Attachment ID, Attachment data array, or Attachment data object.
+ * @return array Empty array on failure. List of taxonomies on success.
+ */
 function get_attachment_taxonomies($attachment) {
         if ( is_int( $attachment ) )
                 $attachment = get_post($attachment);