Changeset 8925

Timestamp:

09/18/2008 06:14:46 AM (16 years ago)

Author:

ryan

Message:

phpdoc for media.php. Props jacobsantos. fixes #7658

File:

• trunk/wp-includes/media.php (modified) (13 diffs)

trunk/wp-includes/media.php

@@ -54 +54 @@
     }
     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'));
@@ -110 +111 @@
  * 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.
@@ -167 +173 @@
  * 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
@@ -198 +211 @@
 }
 
-// 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 )
@@ -218 +244 @@
 }
 
-// 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) {
 
@@ -272 +312 @@
  * 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) {
@@ -343 +393 @@
 }
 
-// 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 ) {
@@ -360 +423 @@
 }
 
+/**
+ * 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 ) ) )
@@ -403 +486 @@
 }
 
-// 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) {
 
@@ -421 +514 @@
 }
 
-// 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 = '';
@@ -440 +543 @@
 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) {
 
@@ -465 +584 @@
 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;
@@ -597 +727 @@
 }
 
+/**
+ * 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 ) )